Improves elevation handling and propagation

dietmarw · dietmarw · commit 66c6ad4e1aa3 · 2026-04-10T16:55:43.000+02:00
Relocates elevation equations (`o.z = i.z` or `o.z = i.z - H`) from the `equation` section to the `initial equation` section for most components. This ensures elevation values are determined once at initialization and then propagated through the connected topology, simplifying model structure and potentially improving simulation performance.

Introduces a `fixElevation` parameter for source and sink models (e.g., `Reservoir`, `VolumeFlowSource`). This parameter allows users to either:
- Enforce a fixed absolute elevation (`z_0`) at the outlet (when `fixElevation` is true, default).
- Allow the outlet elevation to be determined by the connected topology (when `fixElevation` is false), enabling more flexible model configurations where elevation propagates into these components.
diff --git a/OpenHPL/ElectroMech/BaseClasses/BaseValve.mo b/OpenHPL/ElectroMech/BaseClasses/BaseValve.mo
@@ -28,13 +28,14 @@ protected
     annotation (Placement(transformation(origin = {0, 70}, extent = {{-10, -10}, {10, 10}}, rotation = 270), iconTransformation(extent = {{-20, -20}, {20, 20}}, rotation = 270, origin = {0, 80})));
   constant Real epsilon = 5.0e-5 "Constant to ensure robust expression for dp vs flow. Trial and error to find suitable value.";
 
+initial equation
+  o.z = i.z "Elevation propagation: no height change across valve";
 equation
   i.mdot + o.mdot = 0;
   mdot = i.mdot;
   Vdot = mdot/data.rho;
   dp*(C_v_*max(epsilon, u^alpha))^2 = Vdot*abs(Vdot) "Valve equation for pressure drop";
   dp = i.p - o.p "Link the pressure drop to the ports";
-  o.z = i.z "Elevation propagation: no height change across valve";
   annotation (preferredView="info", Documentation(info="<html>
 <p>
 This is a partial, simple model of hydraulic valve. &nbsp;</p><p>This model is based on the energy balance of a valve.
diff --git a/OpenHPL/ElectroMech/Turbines/Francis.mo b/OpenHPL/ElectroMech/Turbines/Francis.mo
@@ -88,6 +88,8 @@ protected
         extent={{-10,-10},{10,10}},
         rotation=90,
         origin={40,90})));
+initial equation
+  o.z = i.z "Elevation propagation: no height change across turbine";
 equation
   // design algorithm for runner
     if GivenData then
@@ -210,7 +212,6 @@ equation
     p_tr2 = o.p;
     i.mdot+o.mdot=0;
     mdot=i.mdot;
-    o.z = i.z "Elevation propagation: no height change across turbine";
 
   connect(p_out, P_out) annotation (Line(points={{40,90},{40,110}}, color={0,0,127}));
     annotation (preferredView="info",
diff --git a/OpenHPL/ElectroMech/Turbines/Pelton.mo b/OpenHPL/ElectroMech/Turbines/Pelton.mo
@@ -30,6 +30,8 @@ protected
         extent={{-10,-10},{10,10}},
         rotation=90,
         origin={40,90})));
+initial equation
+  o.z = i.z "Elevation propagation: no height change across turbine";
 equation
   // Condition for inlet water compressibility
     if not CompElas then
@@ -54,7 +56,6 @@ equation
   // Flow rate connectors
     i.mdot+o.mdot=0;
     mdot=i.mdot;
-    o.z = i.z "Elevation propagation: no height change across turbine";
 
   connect(p_out, P_out) annotation (Line(points={{40,90},{40,110}}, color={0,0,127}));
     annotation (preferredView="info",
diff --git a/OpenHPL/Interfaces/TwoContacts.mo b/OpenHPL/Interfaces/TwoContacts.mo
@@ -7,7 +7,7 @@ partial model TwoContacts "Model of two connectors"
                                annotation (
     Placement(transformation(extent={{90,-10},{110,10}})));
 equation
-  i.gz = 0 "Elevation auxiliary variable (no elevation source/sink at this connection point)";
+  o.gz = i.gz "Elevation auxiliary variable: propagate gz from inlet to outlet";
   annotation (
     Documentation(info = "<html>
     <p>TwoContact is a partial model, which consists of two Contacts <em>i</em>and <em>o</em>.
diff --git a/OpenHPL/Waterway/BendPipe.mo b/OpenHPL/Waterway/BendPipe.mo
@@ -16,14 +16,15 @@ model BendPipe "Bend in pipes"
   SI.Pressure dp "Pressure drop of fitting";
   SI.MassFlowRate mdot "Mass flow rate";
   extends OpenHPL.Interfaces.TwoContacts;
+initial equation
+  o.z = i.z "Elevation propagation: no height change across bend";
 equation
   v = mdot / data.rho / A;
   dp = K_L * 0.5 * data.rho * v^2;
    // Connections
   o.p = i.p - dp "Pressure of the output connector";
   i.mdot + o.mdot = 0 "Mass balance";
   mdot = i.mdot "Flow direction";
-  o.z = i.z "Elevation propagation: no height change across bend";
   annotation (preferredView="info",
     Documentation(info="<html>
 <p>Usually minor head losses in pipes are considered to be due to fittings, diffusers, nozzles, bend in pipes, etc. We are more interested in head loss due to bend pipes for this model.</p>
diff --git a/OpenHPL/Waterway/DraftTube.mo b/OpenHPL/Waterway/DraftTube.mo
@@ -91,6 +91,7 @@ initial equation
     Vdot = Vdot_0;
     //n.T = p.T;
   end if;
+  o.z = i.z - H "Elevation propagation: outlet is H below inlet";
 equation
   der(M) = Mdot + F "Momentum balance";
   if DraftTubeType == OpenHPL.Types.DraftTube.ConicalDiffuser then
@@ -153,7 +154,6 @@ equation
   p_o = o.p;
   i.mdot+o.mdot=0;
   mdot = i.mdot;
-  o.z = i.z - H "Elevation propagation: outlet is H below inlet";
   annotation (preferredView="info", Documentation(info="<html>
     <p>Two of the draft tubes are modeled using <em>Momentum balance</em>.
     They are:</p>
diff --git a/OpenHPL/Waterway/Fitting.mo b/OpenHPL/Waterway/Fitting.mo
@@ -21,6 +21,8 @@ model Fitting "Different pipes fitting"
   Real phi "Dimensionless factor based on the type of fitting ";
   /* Connector */
   extends OpenHPL.Interfaces.TwoContacts;
+initial equation
+  o.z = i.z "Elevation propagation: no height change across fitting";
 equation
   v = mdot / data.rho / A;
   if v>=0 then
@@ -53,7 +55,6 @@ equation
   o.p = i.p - dp "Pressure of the output connector";
   i.mdot+o.mdot = 0 "Mass balance";
   mdot = i.mdot "Flow direction";
-  o.z = i.z "Elevation propagation: no height change across fitting";
   annotation (preferredView="info",
     Documentation(info="<html>
     <p>Various possibilities of the fittings for the pipes with different diameters
diff --git a/OpenHPL/Waterway/Gate.mo b/OpenHPL/Waterway/Gate.mo
@@ -25,6 +25,8 @@ model Gate "Model of a sluice or tainter gate based on [Bollrich2019]"
           extent={{-20,-20},{20,20}},
           rotation=270,
           origin={0,120})));
+initial equation
+  o.z = i.z "Elevation propagation: gate at same elevation";
 equation
   mu_A = psi/sqrt(1+psi*a/h_0);
   if sluice then
@@ -51,7 +53,6 @@ equation
   mdot = Vdot * data.rho "Mass flow rate through the gate";
   i.p = h_0 * data.g * data.rho + data.p_a "Inlet water pressure";
   o.p = h_2 * data.g * data.rho + data.p_a "Outlet water pressure";
-  o.z = i.z "Elevation propagation: gate at same elevation";
   annotation (
     preferredView="info",
     Documentation(info="<html>
diff --git a/OpenHPL/Waterway/Gate_HR.mo b/OpenHPL/Waterway/Gate_HR.mo
@@ -33,6 +33,8 @@ protected
   SI.VolumeFlowRate Vdot_full "Fully submerged base volume flow rate through the gate";
   Real Cdx "Discharge coefficient tuned for a smooth transition between partially and fully submerged";
 
+initial equation
+  o.z = i.z "Elevation propagation: gate at same elevation";
 equation
   i.mdot+o.mdot = 0 "Mass balance";
   mdot = i.mdot "Inlet direction for mdot";
@@ -50,7 +52,6 @@ equation
   mdot = Vdot * data.rho "Mass flow rate through the gate";
   i.p = h_i * data.g * data.rho + data.p_a "Inlet water pressure";
   o.p = h_o * data.g * data.rho + data.p_a "Outlet water pressure";
-  o.z = i.z "Elevation propagation: gate at same elevation";
   annotation (
     preferredView="info",
     Documentation(info="<html>
diff --git a/OpenHPL/Waterway/OpenChannel.mo b/OpenHPL/Waterway/OpenChannel.mo
@@ -30,6 +30,8 @@ model OpenChannel "Open channel model (use KP scheme)"
     boundaryValues=[h_0[1] + H[1],Vdot_i/W; h_0[N] + H[2],Vdot_o/W],
     boundaryCondition=BoundaryCondition,
     SteadyState=SteadyState) annotation (Placement(transformation(extent={{-10,-8},{10,12}})));
+initial equation
+  o.z = i.z - (H[1] - H[2]) "Elevation propagation: channel bed drops from H[1] to H[2]";
 equation
 // define a vector of the water depth in the channel
   h = openChannel.h;
@@ -39,7 +41,6 @@ equation
 // presurre boundaries
   i.p = h[1] * data.g * data.rho + data.p_a;
   o.p = h[N] * data.g * data.rho + data.p_a;
-  o.z = i.z - (H[1] - H[2]) "Elevation propagation: channel bed drops from H[1] to H[2]";
   annotation (preferredView="info",
     Documentation(info="<html>
 <p style=\"color: #ff0000;\"><em>Note: Currently under investigation for plausibility.</em></p>
diff --git a/OpenHPL/Waterway/Penstock.mo b/OpenHPL/Waterway/Penstock.mo
@@ -33,6 +33,7 @@ initial equation
   mdot_V = data.rho * Vdot_0;
   mdot = data.rho * Vdot_0 * ones(N - 2);
   p_ = p_i + dp:dp:p_i + dp * (N - 1);
+  o.z = i.z - H "Outlet elevation is H below inlet";
 equation
   // Pipe flow rate
   mdot_R = i.mdot;
@@ -83,7 +84,6 @@ equation
   // volumetric flow rates for all cells
   V_p_out = mdot ./ rho_m;
   V_p_out_end = mdot_V / (data.rho * (1 + data.beta * (p_o - data.p_a)));
-  o.z = i.z - H "Outlet elevation is H below inlet";
   annotation (preferredView="info",
     Documentation(info="<html><head></head><body><p>This is a more detaied model of the pipe that can be use for proper modeling of penstock. (This model does not work well. Instead PenstockKP model can be used.)</p><p>The model for the penstock with the elastic walls and compressible water with simple discretization method (Staggered grid). The geometry of the penstock is described due to figure:</p>
 <p><img src=\"modelica://OpenHPL/Resources/Images/pipe.svg\"></p>
diff --git a/OpenHPL/Waterway/PenstockKP.mo b/OpenHPL/Waterway/PenstockKP.mo
@@ -54,6 +54,7 @@ initial equation
     mdot[2:N - 1] = data.rho * Vdot_0[2:N - 1];
     p_p = p_p0;
   end if;
+  o.z = i.z - H "Outlet elevation is H below inlet";
 equation
   // Pipe flow rate
   mdot_R = i.mdot;
@@ -115,7 +116,6 @@ equation
   S_[N + 1:2 * N] = F_ap * data.g * H / L - F_f / dx;
   // diff. equation
   der(U) = KP.diff_eq;
-  o.z = i.z - H "Outlet elevation is H below inlet";
   annotation (preferredView="info",
     Documentation(info="<html>
 <h4>Elastic Penstock with KP Method</h4>
diff --git a/OpenHPL/Waterway/Pipe.mo b/OpenHPL/Waterway/Pipe.mo
@@ -61,6 +61,7 @@ initial equation
   else
     Vdot=Vdot_0;
   end if;
+  o.z = i.z - H "Elevation propagation: outlet is H below inlet";
 algorithm
     assert( phi < 1.0,  "Change in pipe diameter is too large. (angle= "+String(phi)+" )",AssertionLevel.warning);
 equation
@@ -73,7 +74,6 @@ equation
   p_o = o.p "Outlet pressure";
   i.mdot+o.mdot = 0 "Mass balance";
   mdot = i.mdot "Inlet direction for mdot";
-  o.z = i.z - H "Elevation propagation: outlet is H below inlet";
 
   annotation (preferredView="info",
     Documentation(info="<html>
diff --git a/OpenHPL/Waterway/Reservoir.mo b/OpenHPL/Waterway/Reservoir.mo
@@ -6,6 +6,8 @@ model Reservoir "Model of the reservoir"
     annotation (Dialog(group="Setup", enable=not useLevel));
   parameter SI.Height z_0=0 "Elevation of the reservoir outlet (sets absolute reference)"
     annotation (Dialog(group="Geometry"));
+  parameter Boolean fixElevation=true "If true (fixed), z_0 is enforced as initial value; if false (derived), elevation is determined by connected topology"
+    annotation (Dialog(group="Geometry"), choices(checkBox=true));
   parameter Boolean constantLevel=false "If checked, the reservoir keeps the constant water level h_0"
     annotation (
     Dialog(group="Setup", enable=not (useInflow or useLevel)),
@@ -52,6 +54,9 @@ initial equation
    if not useLevel then
     h = h_0;
    end if;
+  if fixElevation then
+    o.z = z_0;
+  end if;
 equation
   A =h * (W +h * Modelica.Math.tan(alpha))
     "Vertical cross section of the reservoir";
@@ -79,7 +84,6 @@ equation
   end if;
 
    o.mdot = -data.rho * Vdot_o "Output flow connector";
-  o.z = z_0 "Set absolute elevation at outlet";
   o.gz = 0 "Elevation auxiliary variable";
   //o.T = T_0 "TBD: Output temperature connector";
   annotation (preferredView="info", Documentation(info="<html>
diff --git a/OpenHPL/Waterway/ReservoirChannel.mo b/OpenHPL/Waterway/ReservoirChannel.mo
@@ -13,6 +13,8 @@ model ReservoirChannel "Reservoir model based on open channel model"
   parameter SI.Height h_0=50 "Initial water level of the reservoir";
   parameter SI.Height z_0=0 "Elevation of the reservoir outlet"
     annotation (Dialog(group="Geometry"));
+  parameter Boolean fixElevation=true "If true (fixed), z_0 is enforced as initial value; if false (derived), elevation is determined by connected topology"
+    annotation (Dialog(group="Geometry"), choices(checkBox=true));
   // condition of steady state
   parameter Boolean SteadyState=data.SteadyState "If true, starts in steady state";
   // variables
@@ -28,11 +30,14 @@ model ReservoirChannel "Reservoir model based on open channel model"
     boundaryValues=[h_0 + H[1],q; h_0 + H[2],q],
     boundaryCondition=[true,true; false,true],
     SteadyState=SteadyState) annotation (Placement(transformation(extent={{-10,-10},{10,10}})));
+initial equation
+  if fixElevation then
+    o.z = z_0;
+  end if;
 equation
   // boundaries
   o.mdot =-q*W*data.rho;
   o.p = data.p_a + data.rho * data.g * openChannel.h[N];
-  o.z = z_0 "Set absolute elevation at outlet";
   o.gz = 0 "Elevation auxiliary variable";
   annotation (
     Documentation(preferredView="info", info="<html>
diff --git a/OpenHPL/Waterway/SurgeTank.mo b/OpenHPL/Waterway/SurgeTank.mo
@@ -59,8 +59,7 @@ model SurgeTank "Model of the surge tank/shaft"
 
   Interfaces.Contact_i creek(
     p = p_t + data.rho * data.g * (h - H_creek),
-    mdot = mdot_creek,
-    gz = 0) if useCreekIntake "Creek intake connector (connects to VolumeFlowSource)"
+    mdot = mdot_creek) if useCreekIntake "Creek intake connector (connects to VolumeFlowSource)"
     annotation (Placement(transformation(extent = {{-10, 90}, {10, 110}})));
 
 protected
@@ -73,6 +72,7 @@ initial equation
   else
     h = h_0;
   end if;
+  o.z = i.z "Elevation at surge tank inlet and outlet are equal";
 
 equation
   assert( h >= 0, "Water level h in surge tank must be greater than 0!",
@@ -156,7 +156,6 @@ equation
   i.p = o.p "Inlet and outlet pressure equality";
   mdot = i.mdot+o.mdot "Mass balance";
   F_g = m * data.g * cos_theta;
-  o.z = i.z "Elevation at surge tank inlet and outlet are equal";
  annotation (preferredView="info",
     Documentation(info="<html>
 <h4>Surge Tank Model</h4>
diff --git a/OpenHPL/Waterway/VolumeFlowSource.mo b/OpenHPL/Waterway/VolumeFlowSource.mo
@@ -13,6 +13,8 @@ model VolumeFlowSource "Volume flow source (either fixed or variable)"
     annotation (Dialog(enable=useInput and useFilter));
   parameter SI.Height z_0=0 "Elevation of the outlet connection"
     annotation (Dialog(group="Geometry"));
+  parameter Boolean fixElevation=true "If true (fixed), z_0 is enforced as initial value; if false (derived), elevation is determined by connected topology"
+    annotation (Dialog(group="Geometry"), choices(checkBox=true));
 
   Interfaces.Contact_o o "Outlet flow connector"
     annotation (Placement(transformation(extent={{90,-10},{110,10}})));
@@ -32,13 +34,16 @@ protected
     annotation (Placement(transformation(extent={{0,-10},{20,10}})));
   Modelica.Blocks.Interfaces.RealOutput filtered if useFilter "filtered input"
     annotation (Placement(transformation(extent={{0,-30},{20,-10}})));
+initial equation
+  if fixElevation then
+    o.z = z_0;
+  end if;
 equation
   connect(filtered, Vdot) annotation (Line(
       points={{10,-20},{40,-20},{40,0},{80,0}},
       color={0,0,127},
       pattern=LinePattern.Dot));
   o.mdot = -data.rho*Vdot;
-  o.z = z_0 "Set absolute elevation at outlet";
   o.gz = 0 "Elevation auxiliary variable";
   connect(constantVolumeFlow.y, Vdot) annotation (Line(points={{-39,40},{40,40},{40,0},{80,0}}, color={0,0,127}));
   connect(firstOrder.u, outFlow) annotation (Line(
