Visual enhancement of PartialTwoPort

[justnielsen]

Fluid.Interfaces.PartialTwoPort is widely used as a base class. When I make new components based on this class I am often faced with two limitations.

1. the fluid ports must be 'horizontal'
2. the instance name shown on the icon cannot be hidden or changed

As an example of the first mentioned, in district heating applications heat storage tanks are often visualized with 'vertical' ports while the text inside the icons should be readable (see image below).

As an example of the second issue, system models with many components easily become crowded with unnecesary text labels and flow direction arrows. In that case it would be desirable to hide the instance names in the diagram. In some applications (power generation/district heating) components are labelled with the KKS system (KraftwerkKennzeichenSystem). Rather than giving instance names capital letters according to KKS (and violating Modelica practice) it would be nice to just show the KKS tag or any other user defined label on the diagrams (see other image below).

Suggestion

I suggest the following changes to PartialTwoPort

Two new parameters:

  // Visualization tab
  parameter Integer port_rotation=0 "Rotation of fluid ports"
    annotation (Dialog(tab="Visualization"));
  parameter String icon_label="%name" "Icon label"
    annotation (Dialog(tab="Visualization"));

Modification of fluid ports annotation to

  Modelica.Fluid.Interfaces.FluidPort_a port_a(
    redeclare final package Medium = Medium,
    m_flow(min=if allowFlowReversal then -Modelica.Constants.inf else 0),
    h_outflow(start=Medium.h_default, nominal=Medium.h_default)) 
    "Fluid connector a (positive design flow direction is from port_a to port_b)"
    annotation (Placement(transformation(
        extent={{-110,-10},{-90,10}},
        origin={0,0},
        rotation=port_rotation)));
  Modelica.Fluid.Interfaces.FluidPort_b port_b(
    redeclare final package Medium = Medium,
    m_flow(max=if allowFlowReversal then +Modelica.Constants.inf else 0),
    h_outflow(start=Medium.h_default, nominal=Medium.h_default)) 
    "Fluid connector b (positive design flow direction is from port_a to port_b)"
    annotation (Placement(transformation(
        extent={{110,-10},{90,10}},
        origin={0,0},
        rotation=port_rotation)));

Modification of icon text to

    Text(
      extent={{-149,-114},{151,-154}},
      origin={0,0},
      rotation=port_rotation,
      lineColor={0,0,255},
      textString=icon_label)}));

Impact on other classes

The classes extending from PartialTwoPort can finalize the values of the two new parameters if it does not make sense for the user to change them. Currently, the following classes extend PartialTwoPort:

Fluid\BaseClasses\MassFlowRateMultiplier
Fluid\FixedResistances\BaseClasses\PlugFlow
Fluid\FixedResistances\BaseClasses\PlugFlowCore
Fluid\HeatExchangers\RadiantSlabs\ParallelCircuitsSlab
Fluid\Interfaces\PartialTwoPortInterface
Fluid\Interfaces\PartialTwoPortTransport
Fluid\Sensors\BaseClasses\PartialFlowSensor
Fluid\Sources\BaseClasses\PartialPropertySource

If the suggestion is accepted, similar graphical enhancements could be applied to other classes as well, using a Visualization tab to control the appearance of components.

Best regards Rene Just Nielsen

[Mathadon]

I like the icon label suggestion, but I'm not sure what you'd need the port rotation for?

[justnielsen]

The port rotation is to avoid drawing an icon sideways and then rotating the component when it is instantiated. The topmost figure also shows two pressure controllers where this feature is used to keep the text readable.

[Mathadon]

I'm not sure which are the pressure controllers? How can the port icon be sideways, since the FluidPort is point-symmetric such that it's visual appearance is not affected by a rotation?

[justnielsen]

Sorry, the pressure controllers are the two circles with "PC" inside. It's because the ports are placed with the origin in the centre of the icon {0,0} and not in e.g. {-110,0}. The rotation is performed around their origin.

[Mathadon]

Ok so the rotation is around the component icon origin instead of the fluid port icon origin? In that case, suppose you have a pump, the ports could for instance appear at the top and bottom of the icon instead of left/right. That would not really make sense from an interpretation point of view, and the port would then overlap with the RealInput. Why not simply rotate the entire icon instead of rotation the ports within the icon? Is it to keep all names horizontal? Then simply rotate the names instead of the ports?

[justnielsen]

I agree that in the case with a pump it doesn't make sense to rotate the fluid ports (unless the RealInput and RealOutput are also rotated). The same goes for pipes, valves and other graphically simple components. In their case, port_rotation could simply be finalized to 0 to hide it from the user. But in the case of the mentioned heat storage tank or other 'upright' appearing components I think it is more convenient to draw the icon in the right direction from the beginning.

In addition to components extending from PartialTwoPort it could be relevant to give e.g. heat exchangers different appearances. This could also be enabled in the base class where the fluid ports are defined.

[mwetter]

The port rotation is quite useful for some models, namely the tank, but I would use a protected constant to avoid cluttering up the user interface as this is a setting that in my understanding a component developer would set. In this case, we also need to figure out where to place the label. Alternatively, we could not rotate by move the ports (by asking the coordinates?) as rotating make port_a readable from a different direction than port_b, see below.

I don't quite understand the purpose of the icon label. Why don't you simply name the instance in the way you want the icon label to be? Then, it also shows up correctly in result files, in the fmi model description, and in other tools that use the instance name. I could see users get confused if the name is different, or if there is an assertion that points to an instance name but the schematics shows a different icon label.

For testing I made an implementation on branch issue1280_visualPartialTwoPort. We can discuss on the coordination call on Monday, https://github.com/ibpsa/project1/wiki/2020-01-20-library-development

[justnielsen]

I agree that the in the case of PartialTwoPort the port placement option could be hidden from the end user (protected constant). For other components, like the differential pressure controllers ("PC") shown in the figure of my original post, I find it useful to have user-defined port directions to maintain the readability of the icon. In that case it is often easier to rotate the ports and icon label around the centre of the component rather than rotating all graphical annotations.

I haven't though of the port name rotation in your figure as a problem since the end user spends less time in the diagram view of a component than in the diagram view of the system model (where the port names are hidden). However, since probably only four port placements will be relevant (port_a to port_b):

1. top-to-bottom
2. left-to-right
3. bottom-to-top
4. right-to-left (maybe 1. and 2. will suffice?)

...then it should be straightforward to change the port placements and text label according to an enumeration variable with the two/four options.

As for the text label, the easy solution would be to rotate it with the same angle around {0,0} as the ports. A more complex solution would be to place it centred above/below the icon if the ports are "horizontal" and left/right adjusted on the side of the icon if the ports are "vertical". The last solution will take up more space with the text protruding from the icon.

The purpose of the icon label is mainly to be able to hide the label altogether (as I have done in the figures above). The default value of the icon_label is %name but the user can also to set the value to "" to hide the name or to whatever string value that makes sense to the model diagram (all capital letters, initial digit or "illegal" characters).

In some of our own libraries we also have the options to show/hide

• certain component parameters
• certain calculated values (DynamicSelect)
• 'Function codes'
• ports like y_actual, heatPort and pump power.

on the icon of components. This is my reason for suggesting a new tab called Visualization where these options can be set.

[mwetter]

Discussions from the call:

• Make rotation a constant (or move the port), ensuring that the port label is horizontal and readable (not above/below the port if the connection line goes there.
• Put optional label overwrite as a parameter on the Advanced tab as a Visualization tab with one entry would clutter up the GUI.

[mwetter]

Using portRotation as in 33294ed8b renders fine in Dymola, but OMEdit ignores the rotation. See IBPSA.Fluid.Storage.Examples.Stratified

[mwetter]

Using port coordinates (af2e340d5b38a4310955932fe431930a854c41de) also works in Dymola, but does not render in OMEdit:

[mwetter]

As a work-around, refactor storage model to use a base class that has ports at the top and bottom. Using port coordinates from a constant seems not to be addressed by the standard.

[justnielsen]

@mwetter Thanks for looking into the issue. It's a shame that the solutions don't conform with the standard. Refactoring the heat storage model takes out much of the flexibility.