Refactor: Interfaces should not contain calculated values

[dietmarw]

Currently, the OpenHPL.Interfaces contains

• ContactPort
• ContactNode

which contain both mdot definitions, which are different to each other and might be confusing. A cleaner implementation would be to get rid of both of these interfaces and extend from TwoContact (possibly best to rename to TwoContacts) and include any variable definitions in the models that use it directly.

That way, different interpretations can also be avoided (see mdot in SurgeTank vs Pipe model).

[pandeysudan1]

---

Disclaimer: Checked but AI Generated

Current Implementation in OpenHPL.Interfaces

Currently, we have the following models in the Interfaces package:

---

within OpenHPL.Interfaces;
´´´modelica´´´
connector Contact
  SI.Pressure p "Contact pressure";
  flow SI.MassFlowRate mdot "Mass flow rate through the contact";
end Contact;
connector Contact_i

extends Contact;

end Contact_i;
connector Contact_o

extends Contact;

end Contact_o;
partial model TwoContact

Contact_i i;

Contact_o o;

end TwoContact;
partial model ContactNode

p_n; // node pressure

flow mdot;

extends TwoContact;

equation

p_n = i.p;

i.p = o.p;

mdot = i.mdot + o.mdot;

end ContactNode;
partial model ContactPort

mdot;

extends TwoContact;

equation

0 = i.mdot + o.mdot;

mdot = i.mdot;

end ContactPort;

´´´

These models work functionally. However, the current structure introduces directionality (via Contact_i and Contact_o), which breaks acausal modeling semantics.

---

⚙️ Current Hierarchy and Its Limitation

At present, the hierarchy is:

Contact → Contact_i / Contact_o → TwoContact → ContactPort / ContactNode → Device (e.g., Pipe)

The issue is that by defining input and output connectors separately (Contact_i, Contact_o), the model becomes causal instead of acausal.
In equation-based modeling, the standard approach is to define a single connector that contains the across and through variables, and then use it directly in partial models or components.

---

🧱 Proposed Simplified Structure

We can simplify the modeling chain to:

Contact → ContactPort → Device

This keeps the model acausal and clean.

---

🔹 Proposed ContactPort

within OpenHPL.Interfaces;
/**

ContactPort — Two-port hydraulic connection



Defines a through component with two contacts: inlet and outlet.
Each contact has pressure (p) and mass flow rate (mdot).
Ensures mass conservation and defines the through flow direction.

*/

partial model ContactPort

import Modelica.SIunits;

// --- Connectors ---

Contact i "Inlet hydraulic contact";

Contact o "Outlet hydraulic contact";
// --- Variables ---

SI.MassFlowRate mdot "Mass flow rate through the port";

SI.Pressure dp "Pressure difference between inlet and outlet (i.p - o.p)";
equation

// --- Mass conservation (flow balance) ---

0 = i.mdot + o.mdot;
// --- Define positive flow direction (from inlet to outlet) ---

mdot = i.mdot;
// --- Pressure difference (useful for extensions like pipes/turbines) ---

dp = i.p - o.p;

end ContactPort;

This simplified ContactPort can be easily extended to model devices such as Pipe, Intake, Draft Tube, etc.

---

🌊 Reservoir Analogy

A simple reservoir can be modeled using just the base connector Contact (or renamed HydroPort).
This is analogous to a Ground Pin in the electrical domain — it provides a pressure boundary (constant head).

---

🧩 Node Connection (Three-Port Junction)

For components such as Surge Tanks, which interface with multiple flow paths, a ContactNode can be defined as:

partial model ContactNode
  SI.Pressure p_n "Node pressure";
  flow SI.MassFlowRate mdot "Mass flow through node";
Contact i "Inlet contact";

Contact o "Outlet contact";
equation

// Pressure continuity across node

p_n = i.p;

i.p = o.p;
// Mass conservation across node

mdot = i.mdot + o.mdot;

end ContactNode;

This node can later be expanded to handle three or more ports (for example, a surge tank node connecting intake, penstock, and tank).

---

🧠 Suggested Naming Convention

Old Name	Suggested New Name	Analogy
Contact	HydroPort	Pin (electrical)
ContactPort	OneHydroPort	OnePort (electrical)
ContactNode	HydroPortNode	Node (multi-port junction)

---

✅ Summary

• Contact_i, Contact_o, and TwoContact are redundant and can be dropped.

• The interfaces can be reduced to three clean components:

  • Contact (base connector)

  • ContactPort (two-port interface)

  • ContactNode (junction/manifold)

• Future extensions for energy balance (with temperature) can introduce stream variables as needed.

---

In short:
Move from directional connectors to acausal connectors for clarity, modularity, and Modelica compliance.
The simplified hierarchy makes the OpenHPL interface robust and future-proof for mass–momentum and later energy-based extensions.

How should we approach @dietmarw ?

[dietmarw]

@pandeysudan1 The way the comment is written sounds partly AI generated. Could you just put a disclaimer if this is the case. The reason I'm asking is because just because something is NAMED inlet and outlet (not input and output, mind, though even then it would just be a name) does not make it causal in the modelling way. We needed to call the connector something, and calling them inlet and outlet or i and o is just as valid as calling them 1 and 2. So the analysis should not hang itself up in the naming but in the functionality.

[dietmarw]

Also your comment completly misses the issue that we have a mixture of calculated values and connector variables. Again look at mdot which has different meanings which prompted me creating this issue.

[pandeysudan1]

@pandeysudan1

The way the comment is written sounds partly AI generated. Could you just put a disclaimer if this is the case.

Done.

The reason I'm asking is because just because something is NAMED inlet and outlet (not input and output, mind, though even then it would just be a name) does not make it causal in the modelling way.

You’re right. Hydropower flows are unlike electrical flows. All waterway components have unidirectional flow (with the opposite direction for pumped storage power plants). Only the surge tank has bidirectional flow. To be causal, it’s important to apply equations or relations rather than direct assignments for computation.
The naming convention using “i” for input and “o” for output also seems reasonable to me. From FM1015: Modeling of Dynamic Systems lecture notes, we defined them as influent “i” and effluent “e.” What if we could model both forward and reverse flow, as in the case of a reversible pump-turbine? In ModelingToolkit.jl (Julia), they seem to use “a” and “b” as generic names.

We needed to call the connector something, and calling them inlet and outlet or i and o is just as valid as calling them 1 and 2. So the analysis should not hang itself up in the naming but in the functionality.

I revisited this and realized that modeling can be approached in different ways by combining various partial models, and later using inheritance to make models more structured and modular. Thanks for this comment. I’ll start reviewing the OpenHPL User Guide. I believe you shared the Overleaf link a while ago—could you please resend it?

[dietmarw]

I would feel more comfortable if you removed the ai generated comment and just put in YOUR analysis (which could well be BASED on ai analysis). Just pasting in unchecked AI slop verbatim distracts and does not give any value.

[pandeysudan1]

Disclaimer: Checked but AI Generated

Current Implementation in OpenHPL.Interfaces

Currently, we have the following models in the Interfaces package:

within OpenHPL.Interfaces;
´´´modelica´´´
connector Contact
  SI.Pressure p "Contact pressure";
  flow SI.MassFlowRate mdot "Mass flow rate through the contact";
end Contact;
connector Contact_i
extends Contact;
end Contact_i;
connector Contact_o
extends Contact;
end Contact_o;
partial model TwoContact
Contact_i i;
Contact_o o;
end TwoContact;
partial model ContactNode
p_n; // node pressure
flow mdot;
extends TwoContact;
equation
p_n = i.p;
i.p = o.p;
mdot = i.mdot + o.mdot;
end ContactNode;

partial model ContactPort mdot; extends TwoContact; equation 0 = i.mdot + o.mdot; mdot = i.mdot; end ContactPort; ´´´

These models work functionally. However, the current structure introduces directionality (via Contact_i and Contact_o), which breaks acausal modeling semantics.

Current Hierarchy and Its Limitation

At present, the hierarchy is:

Contact → Contact_i / Contact_o → TwoContact → ContactPort / ContactNode → Device (e.g., Pipe)

The issue is that by defining input and output connectors separately (Contact_i, Contact_o), the model becomes causal instead of acausal. In equation-based modeling, the standard approach is to define a single connector that contains the across and through variables, and then use it directly in partial models or components.

Proposed Simplified Structure

We can simplify the modeling chain to:

Contact → ContactPort → Device

This keeps the model acausal and clean.

Proposed ContactPort

within OpenHPL.Interfaces;
/**

* ContactPort — Two-port hydraulic connection
* 
* Defines a through component with two contacts: inlet and outlet.
* Each contact has pressure (p) and mass flow rate (mdot).
* Ensures mass conservation and defines the through flow direction.
  */
  partial model ContactPort
  import Modelica.SIunits;

// --- Connectors ---
Contact i "Inlet hydraulic contact";
Contact o "Outlet hydraulic contact";
// --- Variables ---
SI.MassFlowRate mdot "Mass flow rate through the port";
SI.Pressure dp "Pressure difference between inlet and outlet (i.p - o.p)";
equation
// --- Mass conservation (flow balance) ---
0 = i.mdot + o.mdot;
// --- Define positive flow direction (from inlet to outlet) ---
mdot = i.mdot;

// --- Pressure difference (useful for extensions like pipes/turbines) --- dp = i.p - o.p; end ContactPort;

This simplified ContactPort can be easily extended to model devices such as Pipe, Intake, Draft Tube, etc.

Reservoir Analogy

A simple reservoir can be modeled using just the base connector Contact (or renamed HydroPort). This is analogous to a Ground Pin in the electrical domain — it provides a pressure boundary (constant head).

Node Connection (Three-Port Junction)

For components such as Surge Tanks, which interface with multiple flow paths, a ContactNode can be defined as:

partial model ContactNode
  SI.Pressure p_n "Node pressure";
  flow SI.MassFlowRate mdot "Mass flow through node";
Contact i "Inlet contact";
Contact o "Outlet contact";
equation
// Pressure continuity across node
p_n = i.p;
i.p = o.p;

// Mass conservation across node mdot = i.mdot + o.mdot; end ContactNode;

This node can later be expanded to handle three or more ports (for example, a surge tank node connecting intake, penstock, and tank).

Suggested Naming Convention

Old Name Suggested New Name Analogy
Contact HydroPort Pin (electrical)
ContactPort OneHydroPort OnePort (electrical)
ContactNode HydroPortNode Node (multi-port junction)

Summary

• Contact_i, Contact_o, and TwoContact are redundant and can be dropped.

• The interfaces can be reduced to three clean components:

  • Contact (base connector)
  • ContactPort (two-port interface)
  • ContactNode (junction/manifold)

• Future extensions for energy balance (with temperature) can introduce stream variables as needed.

In short:
Move from directional connectors to acausal connectors for clarity, modularity, and Modelica compliance.
The simplified hierarchy makes the OpenHPL interface robust and future-proof for mass–momentum and later energy-based extensions.
How should we approach @dietmarw ?

@dietmarw I have extended TwoContacts and deleted ContactPort and ContactNode. The conservation laws are explicitly encoded in the model. The AI generated connector names proposal might be useful as a reference for the future. Pull Request: #66 (comment)