Revised documentation

mwetter · mwetter · commit 7f3b4aa51a7e · 2025-04-15T10:33:17.000-07:00
diff --git a/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIDDerivativeTime.mo b/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIDDerivativeTime.mo
@@ -76,8 +76,7 @@ First implementation.<br/>
 </li>
 </ul>
 </html>", info="<html>
-<p>This block calculates the derivative time of a PID controller.</p>
-<h4>Main equations</h4>
+<p>This block calculates the derivative time of a PID controller as</p>
 <p align=\"center\" style=\"font-style:italic;\">
 T<sub>d</sub> = 0.5 L T/(0.3 L + T),
 </p>
diff --git a/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIDGain.mo b/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIDGain.mo
@@ -82,8 +82,7 @@ First implementation.<br/>
 </li>
 </ul>
 </html>", info="<html>
-<p>This block calculates the control gain of a PID model.</p>
-<h4>Main equations</h4>
+<p>This block calculates the control gain of a PID model as
 <p align=\"center\" style=\"font-style:italic;\">
 k = 1/k<sub>p</sub> + (0.2 + 0.45 T/L),
 </p>
diff --git a/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIDIntegralTime.mo b/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIDIntegralTime.mo
@@ -90,8 +90,7 @@ First implementation.<br/>
 </li>
 </ul>
 </html>", info="<html>
-<p>This block calculates the integral time of a PID model.</p>
-<h4>Main equations</h4>
+<p>This block calculates the integral time of a PID model as
 <p align=\"center\" style=\"font-style:italic;\">
 T<sub>i</sub> = L (0.4 L + 0.8 T)/(L + 0.1 T),
 </p>
diff --git a/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIGain.mo b/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIGain.mo
@@ -124,8 +124,7 @@ First implementation.<br/>
 </li>
 </ul>
 </html>", info="<html>
-<p>This block calculates the control gain of a PI model.</p>
-<h4>Main equations</h4>
+<p>This block calculates the control gain of a PI model as
 <p align=\"center\" style=\"font-style:italic;\">
 k = 0.15/k<sub>p</sub> + (0.35-LT/(L+T)<sup>2</sup>)(T/k<sub>p</sub>/L),
 </p>
diff --git a/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIIntegralTime.mo b/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/AutoTuner/AMIGO/BaseClasses/PIIntegralTime.mo
@@ -125,9 +125,7 @@ First implementation.<br/>
 </ul>
 </html>", info="<html>
 <p>
-This block calculates the integral time of a PI model.
-</p>
-<h4>Main equations</h4>
+This block calculates the integral time of a PI model as</p>
 <p align=\"center\" style=\"font-style:italic;\">
 T<sub>i</sub> = 0.35 L + 13 L T<sup>2</sup>/(T<sup>2</sup> + 12 L T + 7 L<sup>2</sup>),
 </p>
diff --git a/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/FirstOrderAMIGO.mo b/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/FirstOrderAMIGO.mo
@@ -111,7 +111,7 @@ block FirstOrderAMIGO
   Buildings.Controls.OBC.Utilities.PIDWithAutotuning.Relay.ResponseProcess resPro(
     final yHig=yHig - yRef,
     final yLow=yRef - yLow)
-    "Identify the on and off period length, the half period ratio, 
+    "Identify the on and off period length, the half period ratio,
     and the moments when the tuning starts and ends"
     annotation (Placement(transformation(extent={{-20,-60},{0,-40}})));
   Buildings.Controls.OBC.Utilities.PIDWithAutotuning.SystemIdentification.FirstOrderTimeDelay.ControlProcessModel
@@ -222,7 +222,7 @@ protected
     "Check if the setpoint changes"
     annotation (Placement(transformation(extent={{0,100},{20,120}})));
   Buildings.Controls.OBC.CDL.Utilities.Assert assMes3(
-    final message="The setpoint must not change when an autotuning tuning is ongoing. 
+    final message="The setpoint must not change when an autotuning tuning is ongoing.
     This ongoing autotuning will be aborted and the control gains will not be changed.")
     "Warning message when the setpoint changes during tuning process"
     annotation (Placement(transformation(extent={{160,100},{180,120}})));
@@ -405,7 +405,7 @@ Step 2: Extract parameters of a first-order plus time-delay (FOPTD) model
 <ul>
 <li>
 Based on the inputs and outputs from the relay controller, the
-parameters of the FOPTD model is calculated (see 
+parameters of the FOPTD model is calculated (see
 <a href=\"modelica://Buildings.Controls.OBC.Utilities.PIDWithAutotuning.SystemIdentification\">
 Buildings.Controls.OBC.Utilities.PIDWithAutotuning.SystemIdentification</a>).
 The FOPTD is a simplified representation of the control process.
@@ -417,7 +417,7 @@ Step 3: Calculate the PID gains
 <ul>
 <li>
 The PID gains are calculated with the Approximate M-constrained Integral Gain Optimization (AMIGO) method
-based on the FOPTD model parameters (see 
+based on the FOPTD model parameters (see
 <a href=\"modelica://Buildings.Controls.OBC.Utilities.PIDWithAutotuning.AutoTuner.AMIGO\">
 Buildings.Controls.OBC.Utilities.PIDWithAutotuning.AutoTuner.AMIGO</a>).
 </li>
@@ -461,13 +461,13 @@ generated. The ongoing tuning process will be halted, and no adjustments will be
 to the PID parameters.
 </li>
 <li>
-The autotuning must be conducted when the simulation is in a stable state.
+The autotuning must be conducted when the process is in a stable state.
 The user should monitor changes in the independent variables and
-the control variables (e.g., mass flow rate, temperature) over time.
+the controlled variables (e.g., mass flow rate, temperature) over time.
 When the changes in the independent variables are small (e.g., less than 10%),
-and the changes in the control variables are either small or
+and the changes in the controlled variables are either small or
 exhibit regular oscillations,
-the simulation can be considered in a stable state.
+the process can be considered in a stable state.
 </li>
 </ul>
 <h4>Guidance for setting the parameters</h4>
@@ -477,7 +477,7 @@ typical range of the control error <code>r</code>,
 the reference output for the tuning process <code>yRef</code>, the higher and
 lower values for the relay output <code>yHig</code> and <code>yLow</code>, and the
 deadband <code>deaBan</code>.
-These parameters must be specified on a case-by-case basis. 
+These parameters must be specified on a case-by-case basis.
 To set them, the user should conduct the following steps.
 </p>
 <p>
@@ -489,7 +489,7 @@ In the test run, disable the autotuning and keep the independent variables,
 including but not limited to the setpoint value, constant.
 </li>
 <li>
-During the test run, adjust <code>r</code> so that the 
+During the test run, adjust <code>r</code> so that the
 output of the relay controller, <code>rel.yDif</code>,
 stays between 0 and 1.
 </li>
diff --git a/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/Relay/Controller.mo b/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/Relay/Controller.mo
@@ -160,10 +160,9 @@ annotation (defaultComponentName = "relCon",
         coordinateSystem(preserveAspectRatio=false)),
 Documentation(info="<html>
 <p>
-This block generates a relay output <code>yDif</code> which equals to
-<code>(u_m - u_s)/r</code>.
-<code>u_m</code> and <code>u_s</code>
-are the measurement and the setpoint, respectively.
+This block generates a relay output <code>yDif = (u_m - u_s)/r</code>, where
+<code>u_m</code> is the measurement,
+<code>u_s</code> is the setpoint and
 <code>r</code> is the typical range of control error.
 </p>
 <p>
@@ -176,20 +175,20 @@ Step 1: Calculate control error,
 </p>
 <ul>
 <li>
-If the parameter <code>reverseActing = true</code>, set the control error <code>err</code> to
-<code>(u_s - u_m)/r</code>, else set it to <code>(u_m - u_s)/r</code>.
+If the parameter <code>reverseActing = true</code>, set the control error <code>err = (u_s - u_m)/r</code>,
+else set <code>err = (u_m - u_s)/r</code>.
 </li>
 </ul>
 <p>
 Step 2: Calculate <code>y</code> and <code>yOn</code>,
 </p>
 <ul>
 <li>
-If <code>err &gt; deaBan</code> and <code>trigger</code> is <code>true</code>,
+If <code>err &gt; deaBan</code> and <code>trigger = true</code>,
 then <code>y = yHig</code> and <code>yOn = true</code>,
 </li>
 <li>
-else if <code>err &lt; -deaBan</code> and <code>trigger</code> is <code>true</code>,
+else if <code>err &lt; -deaBan</code> and <code>trigger = true</code>,
 then <code>y = yLow</code> and <code>yOn = false</code>,
 </li>
 <li>
diff --git a/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/Relay/ResponseProcess.mo b/Buildings/Controls/OBC/Utilities/PIDWithAutotuning/Relay/ResponseProcess.mo
@@ -126,20 +126,20 @@ First implementation.<br/>
 </ul>
 </html>", info="<html>
 <p>
-This block processes a relay switch output signal and calculates:
+This block processes a relay switch output signal and calculates
 </p>
 <ol>
 <li>
-the length of the on period;
+the length of the on period,
 </li>
 <li>
-the length of the off period;
+the length of the off period,
 </li>
 <li>
-the normalized time delay of the responses;
+the normalized time delay of the responses, and
 </li>
 <li>
-the flags which indicate if the tuning starts and completes, respectively.
+the flags which indicate if the tuning starts and completes.
 </li>
 </ol>
 <p>
