feat: Adds variable efficiency table to Turbine model (#81)

* Adding the Efficiency Tables

We use a new "type" from which custom tables can be created such that they are available via drop down in the turbine parameter dialogue.

* Added documentation.

* Make the table lookup absolute

---------

Co-authored-by: Dietmar Winkler <dietmar.winkler@dwe.no>

Author: dietmarw-se

OpenHPL/ElectroMech/Turbines/Turbine.mo

@@ -11,13 +11,14 @@ model Turbine "Simple turbine model with mechanical connectors"
     annotation (Dialog(group = "Efficiency data"), choices(checkBox = true));
   parameter SI.Efficiency eta_h = 0.9 "Hydraulic efficiency"
     annotation (Dialog(group = "Efficiency data", enable = ConstEfficiency));
-  parameter Real lookup_table[:, :] = [0, 0.4; 0.2, 0.7; 0.5, 0.9; 0.95, 0.95; 1.0, 0.93]
-    "Look-up table for the turbine/valve efficiency, described by a table matrix, where the first column is a pu value of the guide vane opening, and the second column is a pu value of the turbine efficiency."
-    annotation (Dialog(group = "Efficiency data", enable = not ConstEfficiency));
+  replaceable parameter OpenHPL.Types.Efficiency VarEfficiency constrainedby OpenHPL.Types.Efficiency
+    "Look-up table for the turbine efficiency, described by a table matrix,
+     where the first column is a pu value of the opening, and the second column is a pu value of the turbine efficiency."
+    annotation(choicesAllMatching=true, Dialog(group = "Efficiency data", enable = not ConstEfficiency));
   Modelica.Blocks.Math.Feedback lossCorrection
   annotation (Placement(transformation(extent={{-50,70},{-30,90}})));
   Modelica.Blocks.Tables.CombiTable1Dv efficiencyCurve(
-    table=lookup_table,
+    table=VarEfficiency.EffTable,
     smoothness=Modelica.Blocks.Types.Smoothness.ContinuousDerivative,
     extrapolation=Modelica.Blocks.Types.Extrapolation.LastTwoPoints)
     "Efficiency curve of the turbine"
@@ -80,12 +81,66 @@ or it will be calculated from the nominal turbine net head <code>H_n</code> and
 
 <h5>Usage</h5>
 
-<p>Besides hydraulic input and output, there are inputs as the control signal for the valve
+<p>Besides hydraulic input and output, there are inputs as the control signal for the
 opening and also output as the turbine shaft power.</p>
 
-<h5>More Information</h5>
-<p>More info about the model can be found in: <a href=\"modelica://OpenHPL/Resources/Documents/Report.docx\">Resources/Report/Report.docx</a>
-and <a href=\"modelica://OpenHPL.UsersGuide.References\">[Vytvytskyi2019]</a>.</p>
+<h5>Efficiency Options</h5>
+
+<p>Two modes are available, controlled by the Boolean parameter <code>ConstEfficiency</code>
+in the <em>Efficiency data</em> group:</p>
+
+<ul>
+  <li><strong>Constant efficiency</strong> (<code>ConstEfficiency = true</code>, default):
+      The hydraulic efficiency is fixed at the value given by <code>eta_h</code>
+      (default 0.9).  This is suitable for quick studies where a single
+      representative efficiency value is sufficient.</li>
+  <li><strong>Variable efficiency table</strong> (<code>ConstEfficiency = false</code>):
+      Efficiency varies with guide-vane opening according to a lookup table stored
+      in the replaceable record <code>VarEfficiency</code> of type
+      <a href=\"modelica://OpenHPL.Types.Efficiency\">Types.Efficiency</a>.</li>
+</ul>
+
+<h5>Defining a Custom Efficiency Record</h5>
+
+<p>To supply turbine-specific efficiency data, create a new record that extends
+<code>OpenHPL.Types.Efficiency</code> and override <code>EffTable</code>.
+The table must have exactly two columns:</p>
+
+<ol>
+  <li>Guide-vane opening in per-unit (0 = fully closed, 1 = fully open).</li>
+  <li>Corresponding turbine efficiency in per-unit (0 = no conversion, 1 = lossless).</li>
+</ol>
+
+<p>Rows must be sorted in ascending order of the first column.
+Extrapolation beyond the defined range uses the slope of the last two points
+(<code>Modelica.Blocks.Types.Extrapolation.LastTwoPoints</code>), and the curve is
+interpolated with a continuous derivative
+(<code>Modelica.Blocks.Types.Smoothness.ContinuousDerivative</code>).</p>
+
+<p><strong>Example record:</strong></p>
+<blockquote><pre>
+record MyTurbineEfficiency
+  extends OpenHPL.Types.Efficiency(
+    EffTable = [0.00, 0.00;
+                0.20, 0.72;
+                0.50, 0.91;
+                0.80, 0.94;
+                1.00, 0.91]);
+end MyTurbineEfficiency;
+</pre></blockquote>
+
+<p>Place this record in your own package (or directly in the model), then in the
+<em>Efficiency data</em> group of the Turbine:</p>
+<ol>
+  <li>Uncheck <code>ConstEfficiency</code>.</li>
+  <li>Set <code>VarEfficiency</code> to <code>redeclare MyTurbineEfficiency VarEfficiency</code>
+      (or use the drop-down in the parameter dialog, which lists all records compatible with
+      <a href=\"modelica://OpenHPL.Types.Efficiency\">Types.Efficiency</a>).</li>
+</ol>
+
+<p>The base record <a href=\"modelica://OpenHPL.Types.Efficiency\">Types.Efficiency</a>
+already contains a representative default table that can be used as a starting point
+when no measured data are available.</p>
 </html>"), Icon(graphics={Text(
           visible=enable_P_out,
           extent={{30,100},{50,80}},

OpenHPL/Types/Efficiency.mo

@@ -0,0 +1,11 @@
+within OpenHPL.Types;
+record Efficiency "Example record for efficiency curve"
+  extends Modelica.Icons.Record;
+  parameter SI.PerUnit EffTable[:,:] =
+   [0.0, 0.1;
+    0.2, 0.7;
+    0.5, 0.9;
+   0.95, 0.95;
+    1.0, 0.93]
+   "Opening of the nozzle or guide vane vs efficieny (can be hydraulic or overall depending on application).";
+end Efficiency;

OpenHPL/Types/package.order

@@ -1,4 +1,5 @@
 DraftTube
+Efficiency
 Fitting
 FrictionMethod
 Lambda