Updating documentation for variants

ALSETLab · Mar 13, 2024 · e3f5edb · e3f5edb
1 parent 3200306
commit e3f5edb
Show file tree

Hide file tree

Showing 21 changed files with 55 additions and 32 deletions.
diff --git a/Example2/Analysis/AutomationFunctions/linearize_KchangeLinRamping.mo b/Example2/Analysis/AutomationFunctions/linearize_KchangeLinRamping.mo
@@ -39,7 +39,7 @@ ss := Modelica_LinearSystems2.ModelAnalysis.Linearize(
 <ol>
 <li>In the Package Browser, right click on the function and select &quot;Call function...&quot;. This will open the function&apos;s window. </li>
 <p><img src=\"modelica://Example2/Resources/linfun.png\"/></p>
-<li>Enter the time for linearization, <span style=\"font-family: Courier New;\"><a href=\"Example2.Analysis.KchangeLinRamping\">Example2.Analysis.KchangeLinRamping</a></span> will be simulated until that point in time and linearized.</li>
+<li>Enter the time for linearization, <span style=\"font-family: Courier New;\"><a href=\"modelica://Example2.Analysis.KchangeLinRamping\">Example2.Analysis.KchangeLinRamping</a></span> will be simulated until that point in time and linearized.</li>
 <li>In the new function window, click on &quot;Execute&quot;, if successful, messages/results are displayed in the command window and plots will appear in Simulation tab.</li>
 <li>Go back to the function&apos;s own window and click on &quot;Close&quot;. </li>
 </ol>

diff --git a/Example2/Analysis/AutomationFunctions/package.mo b/Example2/Analysis/AutomationFunctions/package.mo
@@ -2,6 +2,6 @@ within Example2.Analysis;
 package AutomationFunctions "Provides functions for automation of simulation and linearization using the models of the upper layer package"
   extends Modelica.Icons.FunctionsPackage;
   annotation (Documentation(info="<html>
-<p>This package contains functions that automate the simulation, plotting and linearization of the models under <a href=\"Example2.Analysis\">Example2.Analysis</a>.</p>
+<p>This package contains functions that automate the simulation, plotting and linearization of the models under <a href=\"modelica://Example2.Analysis\">Example2.Analysis</a>.</p>
 </html>"));
 end AutomationFunctions;
diff --git a/Example2/Analysis/PFVariants/AutomationFunctions/package.mo b/Example2/Analysis/PFVariants/AutomationFunctions/package.mo
@@ -2,6 +2,6 @@ within Example2.Analysis.PFVariants;
 package AutomationFunctions "Provides functions for automation of simulation and linearization using the models of the upper layer package"
   extends Modelica.Icons.FunctionsPackage;
   annotation (Documentation(info="<html>
-<p>This package contains functions that automate the simulation, plotting and linearization of the models under <a href=\"Example2.Analysis\">Example2.Analysis</a>.</p>
+<p>This package contains functions that automate the simulation, plotting and linearization of the models under <a href=\"modelica://Example2.Analysis\">Example2.Analysis</a>.</p>
 </html>"));
 end AutomationFunctions;
diff --git a/Example2/Analysis/PFVariants/RampingRandomLoadAndInput_pf.mo b/Example2/Analysis/PFVariants/RampingRandomLoadAndInput_pf.mo
@@ -80,7 +80,7 @@ equation
     Icon(coordinateSystem(extent={{-100,-100},{100,100}})),preferredView="diagram",
     Documentation(info="<html>
 <p>Main model used for simulation in [1] and [2]. </p>
-<p>To reproduce the results in Fig. 4 of [2], execute the function <a href=\"Example2.Analysis.AutomationFunctions.simulate_and_plot_inputs\">Example2.Analysis.AutomationFunctions.simulate_and_plot_inputs</a> , which sets up the adequate solver settings to minimize run time.</p>
-<p>Please note that running this model takes substantial time compared to example <a href=\"Example2.Analysis.Ramping\">Example2.Analysis.Ramping</a>, the reason is that both random load and probing signals are added to the model which results in an additional computation burden. </p>
+<p>To reproduce the results in Fig. 4 of [2], execute the function <a href=\"modelica://Example2.Analysis.AutomationFunctions.simulate_and_plot_inputs\">Example2.Analysis.AutomationFunctions.simulate_and_plot_inputs</a> , which sets up the adequate solver settings to minimize run time.</p>
+<p>Please note that running this model takes substantial time compared to example <a href=\"modelica://Example2.Analysis.Ramping\">Example2.Analysis.Ramping</a>, the reason is that both random load and probing signals are added to the model which results in an additional computation burden. </p>
 </html>"),preferredView="diagram");
 end RampingRandomLoadAndInput_pf;
diff --git a/Example2/Analysis/PFVariants/Ramping_pf.mo b/Example2/Analysis/PFVariants/Ramping_pf.mo
@@ -24,7 +24,8 @@ model Ramping_pf
     redeclare record Bus = Example2.PFData.Data.BusData.PF_Bus_0,
     redeclare record Loads = Example2.PFData.Data.LoadData.PF_Loads_0,
     redeclare record Trafos = Example2.PFData.Data.TrafoData.PF_Trafos_0,
-    redeclare record Machines = Example2.PFData.Data.MachineData.PF_Machines_0)
+    redeclare record Machines =
+        Example2.PFData.Data.MachineData.PF_Machines_0)
     annotation (Placement(transformation(extent={{58,-40},{138,40}})));
   Modelica.Blocks.Sources.Constant r(k=0) annotation (Placement(transformation(
         extent={{-20,-20},{20,20}},
@@ -74,6 +75,6 @@ equation
     Diagram(coordinateSystem(extent={{-200,-200},{200,200}})),
     Icon(coordinateSystem(extent={{-100,-100},{100,100}})),preferredView="diagram",
     Documentation(info="<html>
-<p>This model illustrates how ramping is applied to move the system to multiple operating points.</p><p>To simulate this model and plot the results, execute the function <a href=\"Example2.Analysis.AutomationFunctions.simulate_and_plot_ramping\">Example2.Analysis.AutomationFunctions.simulate_and_plot_ramping</a> , which sets up the adequate solver settings to minimize run time.</p>
+<p>This model illustrates how ramping is applied to move the system to multiple operating points.</p><p>To simulate this model and plot the results, execute the function <a href=\"modelica://Example2.Analysis.AutomationFunctions.simulate_and_plot_ramping\">Example2.Analysis.AutomationFunctions.simulate_and_plot_ramping</a> , which sets up the adequate solver settings to minimize run time.</p>
 </html>"));
 end Ramping_pf;
diff --git a/Example2/Analysis/PFVariants/package.mo b/Example2/Analysis/PFVariants/package.mo
@@ -3,6 +3,6 @@ package PFVariants "Variants with redeclarable power flow structures for top-lev
   extends Modelica.Icons.VariantsPackage;
   annotation (Documentation(info="<html>
 <p>Uses the system model in Example2.Base.Systems.PFVariants that takes advantage of OpenIPSL data types with nominal attributes and top-level re-parametrization of power flow initial guess data. </p>
-<p>It is recommended that the models within this package are used for derivative works. See more details in the information layer of <a href=\"Example2.PFData\">Example2.PFData</a>.</p>
-</html>"));
+<p>It is recommended that the models within this package are used for derivative works. See more details in the information layer of <a href=\"modelica://Example2.PFData\">Example2.PFData</a>.</p>
+</html>"),preferredView="info");
 end PFVariants;
diff --git a/Example2/Analysis/Ramping.mo b/Example2/Analysis/Ramping.mo
@@ -70,6 +70,6 @@ equation
     Diagram(coordinateSystem(extent={{-200,-200},{200,200}})),
     Icon(coordinateSystem(extent={{-100,-100},{100,100}})),preferredView="diagram",
     Documentation(info="<html>
-<p>This model illustrates how ramping is applied to move the system to multiple operating points.</p><p>To simulate this model and plot the results, execute the function <a href=\"Example2.Analysis.AutomationFunctions.simulate_and_plot_ramping\">Example2.Analysis.AutomationFunctions.simulate_and_plot_ramping</a> , which sets up the adequate solver settings to minimize run time.</p>
+<p>This model illustrates how ramping is applied to move the system to multiple operating points.</p><p>To simulate this model and plot the results, execute the function <a href=\"modelica://Example2.Analysis.AutomationFunctions.simulate_and_plot_ramping\">Example2.Analysis.AutomationFunctions.simulate_and_plot_ramping</a> , which sets up the adequate solver settings to minimize run time.</p>
 </html>"));
 end Ramping;
diff --git a/Example2/Analysis/RampingRandomLoadAndInput.mo b/Example2/Analysis/RampingRandomLoadAndInput.mo
@@ -49,10 +49,10 @@ model RampingRandomLoadAndInput
         extent={{-20,-20},{20,20}},
         origin={0,122})));
 equation
-  connect(zeroInputs.y, plant.uPSS) annotation (Line(points={{-100,80},{-26,80},{-26,17.1429},{53.7143,17.1429}},
-                                                                                                  color={0,0,127}));
-  connect(uL7.y, plant.uLoad7) annotation (Line(points={{-95.9,-57},{-95.9,-60},{-80,-60},{-80,-17.1429},{53.7143,-17.1429}},
-                                                                                                     color={0,0,127}));
+  connect(zeroInputs.y, plant.uPSS) annotation (Line(points={{-100,80},{-26,80},
+          {-26,17.1429},{53.7143,17.1429}},                                                       color={0,0,127}));
+  connect(uL7.y, plant.uLoad7) annotation (Line(points={{-95.9,-57},{-95.9,-60},
+          {-80,-60},{-80,-17.1429},{53.7143,-17.1429}},                                              color={0,0,127}));
   connect(rampingLoad.y,add. u2) annotation (Line(
       points={{-137,-167},{-124,-167},{-124,-152},{-114,-152}},
       color={238,46,47},
@@ -80,7 +80,7 @@ equation
     Icon(coordinateSystem(extent={{-100,-100},{100,100}})),preferredView="diagram",
     Documentation(info="<html>
 <p>Main model used for simulation in [1] and [2]. </p>
-<p>To reproduce the results in Fig. 4 of [2], execute the function <a href=\"Example2.Analysis.AutomationFunctions.simulate_and_plot_inputs\">Example2.Analysis.AutomationFunctions.simulate_and_plot_inputs</a> , which sets up the adequate solver settings to minimize run time.</p>
-<p>Please note that running this model takes substantial time compared to example <a href=\"Example2.Analysis.Ramping\">Example2.Analysis.Ramping</a>, the reason is that both random load and probing signals are added to the model which results in an additional computation burden. </p>
+<p>To reproduce the results in Fig. 4 of [2], execute the function <a href=\"modelica://Example2.Analysis.AutomationFunctions.simulate_and_plot_inputs\">Example2.Analysis.AutomationFunctions.simulate_and_plot_inputs</a> , which sets up the adequate solver settings to minimize run time.</p>
+<p>Please note that running this model takes substantial time compared to example <a href=\"modelica://Example2.Analysis.Ramping\">Example2.Analysis.Ramping</a>, the reason is that both random load and probing signals are added to the model which results in an additional computation burden. </p>
 </html>"),preferredView="diagram");
 end RampingRandomLoadAndInput;
diff --git a/Example2/Analysis/Readme/package.mo b/Example2/Analysis/Readme/package.mo
@@ -0,0 +1,21 @@
+within Example2.Analysis;
+package Readme "Recommended models for derivative work"
+  extends Modelica.Icons.Information;
+  annotation (Documentation(info="<html>
+<p>The models in this layer of the package (i.e. <a href=\"modelica://Example2.Analysis\">Example2.Analysis</a>) are intended to reproduce the work in [1] and [2]. </p>
+<p>However, for derivative works the models under the package <a href=\"modelica://Example2.Analysis.PFVariants\">Example2.Analysis.PFVariants</a> (and associated dependencies) are recommended, as they use OpenIPSL types which implement nominal attributes to help with the intialization process. See more information on this aspect under the information layer of <a href=\"modelica://Example2.PFData\">Example2.PFData</a>.</p>
+<p>The main differences between the examples is:</p>
+<ol>
+<li>In the examples this layer of the package, <a href=\"
+Example2.Analysis\">Example2.Analysis</a>, the power flow intial guess data is provided through the <b>records</b> in <a href=\"
+Example2.Base.Systems.Basic.Data\">Example2.Base.Systems.Basic.Data</a>. To change the data, it is necessary to modify the base model in <a href=\"
+Example2.Base.Systems.Basic.sys\">Example2.Base.Systems.Basic.sys</a> by changing the name of the record in the text layer. This is obviously inconvenient, but also, the types are generic and do not implement those of OpenIPSL.</li>
+<li>In the examples within the sub-package, <a href=\"
+Example2.Analysis.PFVariants\">Example2.Analysis.PFVariants</a>, the <b>hierarchical replaceable records</b> in <a href=\"
+Example2.PFData\">Example2.PFData</a> are used. The data can then be modified at the top-layer of the model by selecting from the available data sets (and/or providing new ones in <a href=\"
+Example2.PFData.Data\">Example2.PFData.Data</a>) by clicking on the &quot;Power Flow Scenario&quot; tab of the &quot;Plant&quot; (instantiation of <a href=\"modelica://Example2.Base.Systems.PFVariants.syspf\">syspf</a>), as the records have been propagated and configured for this purposes, as shown in the screenshot below:</li>
+</ol>
+<p style=\"margin-left: 90px;\"><img src=\"modelica://Example2/../../../../Downloads/pf.png\"/></p>
+<p>It is important to note that even though the models in 1. and 2. above are identical in terms of their equations, the intialization will be different due to the use of the nominal attributes. Read more on this aspect under the information layer of <a href=\"modelica://Example2.PFData\">Example2.PFData</a>.</p>
+</html>"));
+end Readme;
diff --git a/Example2/Analysis/Readme/package.order b/Example2/Analysis/Readme/package.order
diff --git a/Example2/Analysis/package.mo b/Example2/Analysis/package.mo
@@ -10,7 +10,7 @@ package Analysis "Models for simulation and linearization at multiple operating
 <li><span style=\"font-family: Courier New;\">Example2.Analysis.RampingRandomLoadAndInput,</span> illustrates how to add multisine input signal and random load variations (in addition to ramping) to the system in Example2.Base.Systems.sys.</li>
 <li><span style=\"font-family: Courier New;\">Example2.Analysis.KchangeLinRamping</span>, designed to linearize the model Example2.Base.Systems.sys at any point in time while considering ramping as in Example2.Analysis.Ramping</li>
 </ol>
-<p><br><i><b>Sub-package:</b></i> <a href=\"Example2.Analysis.AutomationFunctions\">Example2.Analysis.AutomationFunctions</a></p>
+<p><br><i><b>Sub-package:</b></i> <a href=\"modelica://Example2.Analysis.AutomationFunctions\">Example2.Analysis.AutomationFunctions</a></p>
 <p>This sub-package contains three functions to automate the simulations of models 1 and 2, and to automate the linearization of model 3. See the documentation/info layer of each of the functions for more information.</p>
 </html>"),preferredView="info");
 end Analysis;
diff --git a/Example2/Analysis/package.order b/Example2/Analysis/package.order
@@ -1,3 +1,4 @@
+Readme
 Ramping
 RampingRandomLoadAndInput
 KchangeLinRamping

diff --git a/Example2/Base/Plants/package.mo b/Example2/Base/Plants/package.mo
@@ -2,6 +2,6 @@ within Example2.Base;
 package Plants "Models of plants (generator units) for simulation and linearization"
   extends Modelica.Icons.BasesPackage;
   annotation (Documentation(info="<html>
-<p>See the &quot;Package Content&quot; below for the different plants (generator units) models. See more information in <a href=\"Example2.Readme\">Example2.Readme</a>.</p>
+<p>See the &quot;Package Content&quot; below for the different plants (generator units) models. See more information in <a href=\"modelica://Example2.Readme\">Example2.Readme</a>.</p>
 </html>"),preferredView="info");
 end Plants;
diff --git a/Example2/Base/Systems/Basic/Data/package.mo b/Example2/Base/Systems/Basic/Data/package.mo
@@ -3,14 +3,14 @@ package Data "Power flow data records for network initialization without the use
   extends Modelica.Icons.RecordsPackage;
 annotation (Documentation(info="<html>
 <p>This package contains different sets of data records that can be used to initialize the power network on an initial operating point.</p>
-<p>Note that the templates in this package do not include the type declarations with <span style=\"font-family: Courier New;\">nominal</span> attributes provided by OpenIPSL, which therefore leads to different initialization solutions when the data is used as compared with the package <a href=\"Example2.PFData\">Example2.PFData</a>. This is used to illustrate the use of types with nominal values, observe that in the templates here, no nominal values are used, as compared with the package <a href=\"Example2.PFData\">Example2.PFData</a>, where they are. Observe that this is an important aspect as, &quot;the nominal value can be used by an analysis tool to determine appropriate tolerances or epsilons, or may be used for scaling&quot; (see the Modelica Specification, <a href=\"https://specification.modelica.org/maint/3.5/class-predefined-types-and-declarations.html\">Ch.4.8.6</a>).</p>
+<p>Note that the templates in this package do not include the type declarations with <span style=\"font-family: Courier New;\">nominal</span> attributes provided by OpenIPSL, which therefore leads to different initialization solutions when the data is used as compared with the package <a href=\"modelica://Example2.PFData\">Example2.PFData</a>. This is used to illustrate the use of types with nominal values, observe that in the templates here, no nominal values are used, as compared with the package <a href=\"modelica://Example2.PFData\">Example2.PFData</a>, where they are. Observe that this is an important aspect as, &quot;the nominal value can be used by an analysis tool to determine appropriate tolerances or epsilons, or may be used for scaling&quot; (see the Modelica Specification, <a href=\"https://specification.modelica.org/maint/3.5/class-predefined-types-and-declarations.html\">Ch.4.8.6</a>).</p>
 <p>For example, in this package the voltage mangitude is defined in <span style=\"font-family: Courier New;\">Data.PF_TwoAreas.Voltages</span> as:</p>
 <p style=\"margin-left: 30px;\"><span style=\"font-family: Courier New; color: #0000ff;\">parameter&nbsp;</span></span><span style=\"color: #ff0000;\">Real&nbsp;V1;</p>
 <p>Meanwhile, for the case of the templates in Example2.PFData, OpenIPSL</p>
 <p style=\"margin-left: 30px;\"><span style=\"font-family: Courier New; color: #0000ff;\">parameter&nbsp;</span></span><span style=\"color: #ff0000;\">OpenIPSL.Types.PerUnit&nbsp;V1;</p>
 <p>where the type declaration is:</p>
 <p style=\"margin-left: 30px;\"><span style=\"font-family: Courier New; color: #0000ff;\">type</span>&nbsp;Voltage&nbsp;=&nbsp;<span style=\"font-family: Courier New; color: #ff0000;\">SI.Voltage</span>(nominal&nbsp;=&nbsp;1e4,&nbsp;displayUnit&nbsp;=&nbsp;&quot;kV&quot;);</p>
 <p>This difference will result in different intialization solutions despite having the same power flow data.</p>
-<p>It is recommended that the solution provided in the package <a href=\"Example2.PFData\">Example2.PFData</a> is favored.</p>
+<p>It is recommended that the solution provided in the package <a href=\"modelica://Example2.PFData\">Example2.PFData</a> is favored.</p>
 </html>"),preferredView="info");
 end Data;
diff --git a/Example2/Base/Systems/PFVariants/syspf.mo b/Example2/Base/Systems/PFVariants/syspf.mo
@@ -381,7 +381,7 @@ has \"t1\" propagated.",
 <p><span style=\"font-family: Courier New;\">&nbsp;&nbsp;Q&nbsp;=&nbsp;g1.g1.Q;<span style=\"color: #006400;\">&nbsp;//&nbsp;Reactive&nbsp;power</span></p>
 <p><span style=\"font-family: Courier New;\">&nbsp;&nbsp;AVRin&nbsp;=&nbsp;g1.AVRinput_meas;<span style=\"color: #006400;\">&nbsp;//&nbsp;AVR&nbsp;input,&nbsp;error&nbsp;signal&nbsp;to&nbsp;the&nbsp;avr</span></p>
 <p><span style=\"font-family: Courier New;\">&nbsp;&nbsp;AVRout&nbsp;=&nbsp;g1.AVRoutput_meas;<span style=\"color: #006400;\">&nbsp;//&nbsp;AVR&nbsp;output,&nbsp;Efd</span></p>
-<p>This model includes redeclarable power flow structures for top-level re-parametrization using the <a href=\"Example2.PFData\">Example2.PFData</a> package.</p>
+<p>This model includes redeclarable power flow structures for top-level re-parametrization using the <a href=\"modelica://Example2.PFData\">Example2.PFData</a> package.</p>
 </html>"),
     experiment(
       StopTime=600,

diff --git a/Example2/Base/Systems/package.mo b/Example2/Base/Systems/package.mo
@@ -2,6 +2,6 @@ within Example2.Base;
 package Systems
   extends Modelica.Icons.BasesPackage;
   annotation (Documentation(info="<html>
-<p>Power system models with input/output interfaces for simulation and linearization. See usage in the examples under <a href=\"Example2.Analysis\">Example2.Analysis</a>.</p>
+<p>Power system models with input/output interfaces for simulation and linearization. See usage in the examples under <a href=\"modelica://Example2.Analysis\">Example2.Analysis</a>.</p>
 </html>"),preferredView="info");
 end Systems;
diff --git a/Example2/CustomComponents/PSSChangeParam/PSS4Stages.mo b/Example2/CustomComponents/PSSChangeParam/PSS4Stages.mo
@@ -187,7 +187,7 @@ equation
     Documentation(info="<html>
 <p>Specialized custom PSS model with Four Stages </p>
 <p>This PSS is comprised of four different PSS models (PSSTypeII) internally. </p>
-<p>The output of each of them is enabled or disabled through a <a href=\"Example2.CustomComponents.TimedInputInjectionOnOff\">Example2.CustomComponents.TimedInputInjectionOnOff</a> component such that only the output of one of them is injected. </p>
+<p>The output of each of them is enabled or disabled through a <a href=\"modelica://Example2.CustomComponents.TimedInputInjectionOnOff\">Example2.CustomComponents.TimedInputInjectionOnOff</a> component such that only the output of one of them is injected. </p>
 <p>This allows to &quot;emulate&quot; the change of parameters of a conventional PSS that would be represented by a single &quot;structure&quot;, i.e., the block diagram of PSSTypeII, for a user-specified time-period.</p>
 </html>"));
 end PSS4Stages;