Addressing requested changes from Dietmar

lvanfretti · lvanfretti · commit 50395e05f2a7 · 2024-09-26T09:57:09.000-04:00
diff --git a/OpenIPSL/Electrical/Sources/SourceBehindImpedance/BaseClasses/baseVoltageSource.mo b/OpenIPSL/Electrical/Sources/SourceBehindImpedance/BaseClasses/baseVoltageSource.mo
@@ -2,9 +2,7 @@ within OpenIPSL.Electrical.Sources.SourceBehindImpedance.BaseClasses;
 partial model baseVoltageSource
   "Base model for voltage sources behind an impedance"
   outer OpenIPSL.Electrical.SystemBase SysData;
-
   import Modelica.Blocks.Interfaces.*;
-
   extends OpenIPSL.Electrical.Essentials.pfComponent(
     final enabledisplayPF=false,
     final enablefn=false,
@@ -14,13 +12,11 @@ partial model baseVoltageSource
     final enableQ_0=true,
     final enableP_0=true,
     final enableS_b=true);
-
-  // Instantiation of graphical components
   OpenIPSL.Interfaces.PwPin_p p(
     vr(start=vr0),
     vi(start=vi0),
     ir(start=ir0),
-    ii(start=ii0))
+    ii(start=ii0)) "Instantiation of graphical component PwPin_p"
     annotation (Placement(transformation(extent={{100,-10},{120,10}}),
         iconTransformation(extent={{100,-10},{120,10}})));
   RealOutput Emag(start=E0) "Internal voltage magnitude"
@@ -45,66 +41,44 @@ partial model baseVoltageSource
         iconTransformation(extent={{-10,-10},{10,10}},
         rotation=270,
         origin={40,-110})));
-
- // Voltage Source Parameters
   parameter OpenIPSL.Types.ApparentPower M_b=SysData.S_b "Voltage Source base power rating (MVA)"
     annotation (Dialog(group="Voltage Source parameters"));
   parameter OpenIPSL.Types.PerUnit R_a=1e-3 "Internal source resistance, pu, system base"
     annotation (Dialog(group="Voltage Source parameters"));
   parameter OpenIPSL.Types.PerUnit X_d=0.2 "Internal source d-axis reactance, pu, system base"
     annotation (Dialog(group="Voltage Source parameters"));
-
- // Terminal Voltage variables
   OpenIPSL.Types.PerUnit V(start=v_0) "Bus voltage magnitude";
   OpenIPSL.Types.Angle anglev(start=angle_0) "Bus voltage angle";
-
-  // Public Auxiliary variables
   OpenIPSL.Types.PerUnit P(start=P_0/S_b) "Active power (system base)";
   OpenIPSL.Types.PerUnit Q(start=Q_0/S_b) "Reactive power (system base)";
-
-  // Public Internal voltage source variables (to be used as outputs for intialization of linked components, e.g. droop controller)
   OpenIPSL.Types.Angle delta(start=delta0) "Internal voltage source angle";
   OpenIPSL.Types.PerUnit E(start=E0) "Internal voltage source magnitude";
-
 protected
-
-  // Change of base
   parameter Real CoB=M_b/S_b "Change from system to machine base";
-  parameter Real p0=P_0/M_b
-    "Initial active power (machine base)";
-  parameter Real q0=Q_0/M_b
-    "Initial reactive power (machine base)";
-
-  // Initialization values
-  parameter OpenIPSL.Types.PerUnit vr0=v_0*cos(angle_0);
-  parameter OpenIPSL.Types.PerUnit vi0=v_0*sin(angle_0);
-  parameter OpenIPSL.Types.PerUnit ir0=-CoB*(p0*vr0 + q0*vi0)/(vr0^2 + vi0^2);
-  parameter OpenIPSL.Types.PerUnit ii0=-CoB*(p0*vi0 - q0*vr0)/(vr0^2 + vi0^2);
-
-  // Initialization of voltage source parameters
+  parameter Real p0=P_0/M_b "Initial active power (machine base)";
+  parameter Real q0=Q_0/M_b "Initial reactive power (machine base)";
+  parameter OpenIPSL.Types.PerUnit vr0=v_0*cos(angle_0) "Initial value of the real part of the terminal voltage";
+  parameter OpenIPSL.Types.PerUnit vi0=v_0*sin(angle_0) "Initial value of the imaginary part of the terminal voltage";
+  parameter OpenIPSL.Types.PerUnit ir0=-CoB*(p0*vr0 + q0*vi0)/(vr0^2 + vi0^2) "Initial value of the real part of the current";
+  parameter OpenIPSL.Types.PerUnit ii0=-CoB*(p0*vi0 - q0*vr0)/(vr0^2 + vi0^2) "Initial value of the imaginary part of the current";
   parameter OpenIPSL.Types.PerUnit Er0 = vr0 + CoB*R_a*ir0 - CoB*X_d*ii0 "Initial value of the real part of the internal voltage source phasor";
   parameter OpenIPSL.Types.PerUnit Ei0 = vi0 + CoB*R_a*ii0 + CoB*X_d*ir0 "Initial value of the imaginary part of the internal voltage source phasor";
   parameter OpenIPSL.Types.PerUnit E0  = sqrt(Er0^2+Ei0^2) "Initial value of the internal voltage source phasor magnitude";
   parameter OpenIPSL.Types.Angle delta0 = atan2(Ei0, Er0) "Initial value of the internal voltage source phasor angle";
-
-  // Internal voltage source variables
   Real Er(start=Er0) "Internal voltage source, real part";
   Real Ei(start=Ei0) "Internal voltage source, imaginary part";
 equation
-  // Equations linking the internal voltage source to the terminal bus and the pin
-  Er = p.vr + CoB*R_a*(-p.ir) - CoB*X_d*(-p.ii);
-  Ei = p.vi + CoB*R_a*(-p.ii) + CoB*X_d*(-p.ir);
-  //Power injections
-  -P = p.vr*p.ir + p.vi*p.ii;
-  -Q = p.vi*p.ir - p.vr*p.ii;
-  // Terminal voltage magnitude and angle
-  V = sqrt(p.vr^2 + p.vi^2);
-  anglev = atan2(p.vi, p.vr);
+  Er = p.vr + CoB*R_a*(-p.ir) - CoB*X_d*(-p.ii) "Equation linking the internal voltage source to the terminal bus and the pin";
+  Ei = p.vi + CoB*R_a*(-p.ii) + CoB*X_d*(-p.ir) "Equation linking the internal voltage source to the terminal bus and the pin";
+  -P = p.vr*p.ir + p.vi*p.ii "Active power injection";
+  -Q = p.vi*p.ir - p.vr*p.ii "Reactive power injection";
+  V = sqrt(p.vr^2 + p.vi^2) "Terminal voltage magnitude";
+  anglev = atan2(p.vi, p.vr) "Terminal voltage angle";
   // Assining variables to outputs
-  Emag = sqrt(Er^2+Ei^2);
-  Edelta = atan2(Ei,Er);
-  Emag0 = E0;
-  Eang0 = delta0;
+  Emag = sqrt(Er^2+Ei^2) "Attaching a variable to the RealOutput Emag of the model";
+  Edelta = atan2(Ei,Er) "Attaching a variable to the RealOutput Edelta of the model";
+  Emag0 = E0 "Attaching the initial value to the RealOutput Emag0";
+  Eang0 = delta0 "Attaching the initial value to the RealOutput Eang0";
   annotation (Icon(graphics={
         Ellipse(extent={{-100,100},{100,-100}},
                                            lineColor={0,0,255},
@@ -118,9 +92,5 @@ The initial values of the internal voltage source magnitude and angle are calcul
 
 It is based on [Du2021], with the difference that the internal impedance includes a resistance and not only a reactance. </p>
 
-<p>
-[Du2021] W. Du, Y. Liu, F.K. Tuffner, R. Huang and Z. Huang: &quot;Model Specification of Droop-Controlled Grid-Forming Inverters (REGFM_A1)&quot;, Richland, WA, USA: Pacific Northwest National Laboratory, September 2021. <a href=\"https://www.pnnl.gov/main/publications/external/technical_reports/PNNL-32278.pdf\">document</a> 
-</p>
-
 </html>"));
 end baseVoltageSource;
diff --git a/OpenIPSL/Electrical/Sources/SourceBehindImpedance/VoltageSources/VSource.mo b/OpenIPSL/Electrical/Sources/SourceBehindImpedance/VoltageSources/VSource.mo
@@ -35,17 +35,7 @@ equation
           extent={{-100,140},{100,100}},
           textColor={0,0,0},
           textString="%name")}), Documentation(info="<html>
-<p>
-This model provides a voltage source with an internal (constant) voltage source and internal impedance. 
-
-The internal voltage source magnitude and angle are calculated based on the impedance and power flow data. 
-
-It is based on [Du2021], with the difference that the internal impedance includes a resistance and not only a reactance. 
-</p>
-
-<p>
-[Du2021] W. Du, Y. Liu, F.K. Tuffner, R. Huang and Z. Huang: &quot;Model Specification of Droop-Controlled Grid-Forming Inverters (REGFM_A1)&quot;, Richland, WA, USA: Pacific Northwest National Laboratory, September 2021. <a href=\"https://www.pnnl.gov/main/publications/external/technical_reports/PNNL-32278.pdf\">document</a> 
-</p>
-
+<p>This model provides a voltage source with an internal (constant) voltage source and internal impedance.</p>
+<p>See the documentation of <a href=\"Modelica://OpenIPSL.Electrical.Sources.SourceBehindImpedance.BaseClasses.baseVoltageSource\">BaseClasses.baseVoltageSource</a> for more information.</p>
 </html>"));
 end VSource;
diff --git a/OpenIPSL/Electrical/Sources/SourceBehindImpedance/VoltageSources/VSourceIO.mo b/OpenIPSL/Electrical/Sources/SourceBehindImpedance/VoltageSources/VSourceIO.mo
@@ -3,7 +3,6 @@ model VSourceIO
   "Generic voltage source behind an internal impedance with inputs that vary the internal source magnitude and angle from steady state"
   extends BaseClasses.baseVoltageSource;
   // Input ports and polar to rectangular conversion
-public
   Modelica.Blocks.Interfaces.RealInput uDEmag(start=0)
     "Input to vary the voltage magnitude of the voltage source"
     annotation (Placement(transformation(extent={{-140,40},{-100,80}})));
@@ -99,19 +98,8 @@ which are the real and imaginary input
           textString="%name")}),
     Documentation(info="<html>
 <p>
-This model provides a voltage source with an internal voltage source and internal impedance whose magnitude and angle can be varied via inputs starting from their initial values. 
-
-The initial values of the internal voltage source magnitude and angle are calculated based on the impedance and power flow data. 
-
-It is based on [Du2021], with the difference that the internal impedance includes a resistance and not only a reactance. 
-
-The purpose of this model is to support the development of Grid-Forming Inverter models as described in [Du2021].
+The purpose of this model is to support the development of Grid-Forming Inverter models as described in [Du2021]. The model provides a voltage source with an internal voltage source and internal impedance whose magnitude and angle can be varied via inputs starting from their initial values.
 </p>
-
-
-<p>
-[Du2021] W. Du, Y. Liu, F.K. Tuffner, R. Huang and Z. Huang: &quot;Model Specification of Droop-Controlled Grid-Forming Inverters (REGFM_A1)&quot;, Richland, WA, USA: Pacific Northwest National Laboratory, September 2021. <a href=\"https://www.pnnl.gov/main/publications/external/technical_reports/PNNL-32278.pdf\">document</a> 
-</p>
-
+<p>See the documentation of <a href=\"Modelica://OpenIPSL.Electrical.Sources.SourceBehindImpedance.BaseClasses.baseVoltageSource\">BaseClasses.baseVoltageSource</a> for more information.</p>
 </html>"));
 end VSourceIO;
diff --git a/OpenIPSL/Electrical/Sources/SourcesWithRealInputs/CurrentSourceReImInput.mo b/OpenIPSL/Electrical/Sources/SourcesWithRealInputs/CurrentSourceReImInput.mo
@@ -1,4 +1,4 @@
-within OpenIPSL.Electrical.Sources;
+within OpenIPSL.Electrical.Sources.SourcesWithRealInputs;
 model CurrentSourceReImInput
   "Ideal current source with user defined real and imaginary parts of the current phasor"
   extends OpenIPSL.Electrical.Essentials.pfComponent(enableS_b = true);
diff --git a/OpenIPSL/Electrical/Sources/SourcesWithRealInputs/VoltageSourceReImInput.mo b/OpenIPSL/Electrical/Sources/SourcesWithRealInputs/VoltageSourceReImInput.mo
@@ -1,4 +1,4 @@
-within OpenIPSL.Electrical.Sources;
+within OpenIPSL.Electrical.Sources.SourcesWithRealInputs;
 model VoltageSourceReImInput
   "Ideal voltage source with user defined real and imaginary parts of the voltage phasor"
   extends OpenIPSL.Electrical.Essentials.pfComponent(enableS_b=true);
diff --git a/OpenIPSL/Electrical/Sources/SourcesWithRealInputs/package.mo b/OpenIPSL/Electrical/Sources/SourcesWithRealInputs/package.mo
@@ -0,0 +1,5 @@
+within OpenIPSL.Electrical.Sources;
+package SourcesWithRealInputs
+  "Provides voltage and current sources who's inputs are RealInput interfaces to couple with data."
+  extends Modelica.Icons.Package;
+end SourcesWithRealInputs;
diff --git a/OpenIPSL/Electrical/Sources/SourcesWithRealInputs/package.order b/OpenIPSL/Electrical/Sources/SourcesWithRealInputs/package.order
@@ -0,0 +1,2 @@
+CurrentSourceReImInput
+VoltageSourceReImInput
diff --git a/OpenIPSL/Electrical/Sources/package.order b/OpenIPSL/Electrical/Sources/package.order
@@ -1,3 +1,2 @@
-VoltageSourceReImInput
-CurrentSourceReImInput
 SourceBehindImpedance
+SourcesWithRealInputs
diff --git a/OpenIPSL/Tests/BaseClasses/SMIBAddOn.mo b/OpenIPSL/Tests/BaseClasses/SMIBAddOn.mo
@@ -32,7 +32,8 @@ partial model SMIBAddOn
     annotation (Placement(transformation(extent={{18,-10},{38,10}})));
   OpenIPSL.Electrical.Buses.Bus GEN2
     annotation (Placement(transformation(extent={{60,-10},{80,10}})));
-  Electrical.Sources.VoltageSourceReImInput voltageSourceReImInput
+  Electrical.Sources.SourcesWithRealInputs.VoltageSourceReImInput
+    voltageSourceReImInput
     annotation (Placement(transformation(extent={{96,-10},{76,10}})));
   Modelica.Blocks.Sources.RealExpression imagPart annotation (Placement(transformation(extent={{80,-30},{100,-10}})));
   Modelica.Blocks.Sources.RealExpression realPart(y=if time <= 50000 then 1 else 0.99) annotation (Placement(transformation(extent={{80,10},{100,30}})));
diff --git a/OpenIPSL/Tests/Sources/SourcesBehindImpedance/VSource.mo b/OpenIPSL/Tests/Sources/SourcesBehindImpedance/VSource.mo
@@ -17,5 +17,5 @@ equation
   connect(VS.p, GEN1.p)
     annotation (Line(points={{-39,0},{-30,0}}, color={0,0,255}));
 annotation(preferredView="diagram", Documentation(info="<html>
-</html>"));
+</html>"),experiment(StopTime=10));
 end VSource;
diff --git a/OpenIPSL/Tests/Sources/SourcesBehindImpedance/VSourceIO.mo b/OpenIPSL/Tests/Sources/SourcesBehindImpedance/VSourceIO.mo
@@ -30,7 +30,6 @@ equation
           {-62,6}}, color={0,0,127}));
   connect(DEang.y, VSIO.uDEang) annotation (Line(points={{-79,-30},{-72,-30},{
           -72,-6},{-62,-6}}, color={0,0,127}));
-annotation(preferredView="diagram", experiment(StopTime=10,
-        __Dymola_Algorithm="Dassl"));
+annotation(preferredView="diagram", experiment(StopTime=10));
 
 end VSourceIO;
diff --git a/OpenIPSL/Tests/Sources/SourcesBehindImpedance/package.mo b/OpenIPSL/Tests/Sources/SourcesBehindImpedance/package.mo
@@ -3,5 +3,4 @@ package SourcesBehindImpedance
   "Tests models of sources behind impedances with the grid template"
   extends Modelica.Icons.ExamplesPackage;
 
-  annotation();
 end SourcesBehindImpedance;
diff --git a/OpenIPSL/Tests/Sources/SourcesWithRealInputs/CurrentSourceReImInputConstant.mo b/OpenIPSL/Tests/Sources/SourcesWithRealInputs/CurrentSourceReImInputConstant.mo
@@ -1,12 +1,12 @@
-within OpenIPSL.Tests.Sources;
+within OpenIPSL.Tests.Sources.SourcesWithRealInputs;
 model CurrentSourceReImInputConstant
   "Test model for the VoltageSourceReImInput model with constant input"
   extends BaseClasses.SMIB;
   Modelica.Blocks.Sources.Constant vRe(k=1)
     annotation (Placement(transformation(extent={{-96,14},{-84,26}})));
   Modelica.Blocks.Sources.Constant vIm(k=0)
     annotation (Placement(transformation(extent={{-96,-26},{-84,-14}})));
-  Electrical.Sources.CurrentSourceReImInput iSource
+  Electrical.Sources.SourcesWithRealInputs.CurrentSourceReImInput iSource
     annotation (Placement(transformation(extent={{-60,-10},{-40,10}})));
 equation
   connect(iSource.p, GEN1.p)
diff --git a/OpenIPSL/Tests/Sources/SourcesWithRealInputs/VoltageSourceReImInputConstant.mo b/OpenIPSL/Tests/Sources/SourcesWithRealInputs/VoltageSourceReImInputConstant.mo
@@ -1,4 +1,4 @@
-within OpenIPSL.Tests.Sources;
+within OpenIPSL.Tests.Sources.SourcesWithRealInputs;
 model VoltageSourceReImInputConstant
   "Test model for the VoltageSourceReImInput model with constant input"
   extends BaseClasses.SMIB;
@@ -8,7 +8,7 @@ model VoltageSourceReImInputConstant
   replaceable
   Modelica.Blocks.Sources.Constant vIm(k=0) constrainedby Modelica.Blocks.Interfaces.SO
     annotation (Placement(transformation(extent={{-96,-26},{-84,-14}})));
-  Electrical.Sources.VoltageSourceReImInput vSource
+  Electrical.Sources.SourcesWithRealInputs.VoltageSourceReImInput vSource
     annotation (Placement(transformation(extent={{-60,-10},{-40,10}})));
 equation
   connect(vSource.p, GEN1.p)
diff --git a/OpenIPSL/Tests/Sources/SourcesWithRealInputs/VoltageSourceReImInputVaryImag.mo b/OpenIPSL/Tests/Sources/SourcesWithRealInputs/VoltageSourceReImInputVaryImag.mo
@@ -1,7 +1,8 @@
-within OpenIPSL.Tests.Sources;
+within OpenIPSL.Tests.Sources.SourcesWithRealInputs;
 model VoltageSourceReImInputVaryImag
   "Test model for the VoltageSourceReImInput model with varying the imaginary part"
-  extends VoltageSourceReImInputConstant(redeclare Modelica.Blocks.Sources.Ramp vIm(
+  extends SourcesWithRealInputs.VoltageSourceReImInputConstant
+                                        (redeclare Modelica.Blocks.Sources.Ramp vIm(
       height=3.14/8,
       duration=2.5,
       startTime=5));
diff --git a/OpenIPSL/Tests/Sources/SourcesWithRealInputs/VoltageSourceReImInputVaryReal.mo b/OpenIPSL/Tests/Sources/SourcesWithRealInputs/VoltageSourceReImInputVaryReal.mo
@@ -1,7 +1,8 @@
-within OpenIPSL.Tests.Sources;
+within OpenIPSL.Tests.Sources.SourcesWithRealInputs;
 model VoltageSourceReImInputVaryReal
   "Test model for the VoltageSourceReImInput model with varying real part"
-  extends VoltageSourceReImInputConstant(redeclare Modelica.Blocks.Sources.Ramp vRe(
+  extends SourcesWithRealInputs.VoltageSourceReImInputConstant
+                                        (redeclare Modelica.Blocks.Sources.Ramp vRe(
       height=0.1,
       duration=2.5,
       offset=1,
diff --git a/OpenIPSL/Tests/Sources/SourcesWithRealInputs/VoltageSourceReImInputVaryRealAndImag.mo b/OpenIPSL/Tests/Sources/SourcesWithRealInputs/VoltageSourceReImInputVaryRealAndImag.mo
@@ -1,7 +1,8 @@
-within OpenIPSL.Tests.Sources;
+within OpenIPSL.Tests.Sources.SourcesWithRealInputs;
 model VoltageSourceReImInputVaryRealAndImag
   "Test model for the VoltageSourceReImInput model with varying real and imaginary parts"
-  extends VoltageSourceReImInputConstant(
+  extends SourcesWithRealInputs.VoltageSourceReImInputConstant
+                                        (
     redeclare Modelica.Blocks.Sources.Ramp vRe(
       height=0.1,
       duration=2.5,
diff --git a/OpenIPSL/Tests/Sources/SourcesWithRealInputs/package.mo b/OpenIPSL/Tests/Sources/SourcesWithRealInputs/package.mo
@@ -0,0 +1,5 @@
+within OpenIPSL.Tests.Sources;
+package SourcesWithRealInputs
+  "Tests models of sources with RealInput interfaces that can be used to link with data."
+  extends Modelica.Icons.ExamplesPackage;
+end SourcesWithRealInputs;
diff --git a/OpenIPSL/Tests/Sources/SourcesWithRealInputs/package.order b/OpenIPSL/Tests/Sources/SourcesWithRealInputs/package.order
@@ -0,0 +1,5 @@
+CurrentSourceReImInputConstant
+VoltageSourceReImInputConstant
+VoltageSourceReImInputVaryImag
+VoltageSourceReImInputVaryReal
+VoltageSourceReImInputVaryRealAndImag
diff --git a/OpenIPSL/Tests/Sources/package.order b/OpenIPSL/Tests/Sources/package.order
@@ -1,6 +1,2 @@
-VoltageSourceReImInputConstant
-VoltageSourceReImInputVaryReal
-VoltageSourceReImInputVaryImag
-VoltageSourceReImInputVaryRealAndImag
-CurrentSourceReImInputConstant
 SourcesBehindImpedance
+SourcesWithRealInputs
diff --git a/OpenIPSL/UsersGuide/References.mo b/OpenIPSL/UsersGuide/References.mo
@@ -12,6 +12,17 @@ model References "References"
         <a href=\"https://doi.org/10.1109/9780470545577.app4\">DOI: 10.1109/9780470545577.app4</a>
 </td>
 </tr>
+
+<tr>
+<td>[Du2021]</td>
+<td>W. Du, Y. Liu, F.K. Tuffner, R. Huang and Z. Huang:
+        &quot;Model Specification of Droop-Controlled Grid-Forming Inverters (REGFM_A1)&quot;.
+        Richland, WA, USA: Pacific Northwest National Laboratory, September 2021.
+         <a href=\"https://www.pnnl.gov/main/publications/external/technical_reports/PNNL-32278.pdf\">document</a>
+</td>
+</tr>
+
+
 <tr>
 <td>[IEEE1968]</td>
 <td>IEEE:

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-within OpenIPSL.Electrical.Sources;`
	`1`	`+within OpenIPSL.Electrical.Sources.SourcesWithRealInputs;`
`2`	`2`	`model CurrentSourceReImInput`
`3`	`3`	`"Ideal current source with user defined real and imaginary parts of the current phasor"`
`4`	`4`	`extends OpenIPSL.Electrical.Essentials.pfComponent(enableS_b = true);`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+CurrentSourceReImInput`
	`2`	`+VoltageSourceReImInput`