Library Restructuring

Library Structure

This page describes the design proposed in May 2017 for the new structure of the IBPSA library. It is a design document meant to outline and discuss the changes within the IBPSA library development team.

The rationale for the change is that for users, as well as for EnergyPlus/OpenStudio, the library should be closer to what HVAC engineers typically deal with. For example, we will need to have packages such as

Buildings.Air.Fans.xxx
             .Humidifiers.Steam_X
                         .SprayAirWasher_X
         .Water.Pumps.xxx

rather than

Buildings.Fluid.Movers.xxx
         .MassExchangers.SteamHumidifier_X
                        .SprayAirWasher_X

The rationale is to make it easier for users to find and use models, and to avoid having to set the medium.

Having Air and Water parallel to Fluid is probably easiest to understand.

Also, we need some 4 ports models for air-to-water heat exchangers that have ports such as

wat_a  ---------  wat_b
      |         |
air_b  ---------  air_a

rather than

port_a1 --------- port_b1
        |       |
port_b2 --------- port_a2

as it is not obvious that index 1 is water and 2 is air. Similarly, we will also need to have parameters such as mWat_flow_nominal rather than m1_flow_nominal (which is inherited from the base class) as associating 1 with water and 2 with air is inconvenient.

Also, chillers and heat pumps would ideally have ports

con_a  ---------  con_b
      |         |
eva_b  ---------  eva_a

Therefore, this issue is to add packages IBPSA.Air and IBPSA.Water and do the following

1. Move models that can only work with one of the medium, such as the humidifier, to IBPSA.Air or IBPSA.Water (e.g., for the expansion vessel) and assign the respective media.
2. Extend, instantiate, or copy other models such as the Movers and some Sensors in IBPSA.{Air,Water}, assign the respective media and copy the documentation (which is not ideal but needed so that the doc is together with the model). There are quite a few models that need to be in both packages, and some would need to be renamed. For example, a mover becomes a fan or pump.
3. Add new base classes to allow better port names such as {air,wat}_{a,b}.

Note that we will attempt that any copied model is copied with a script, and will contain a clear identification that shows what the source of the file is so that bug fixes need to be applied only once (at the source model) and the files can be copied again. There should be one script that copies all models, and this script can be part of the regression tests to ensure that any upstream bugfixes are implemented in the downstream model.

We propose the following library structure (not all classes are shown, and the top-level IBPSA is omitted):

.Fluid.Movers // keep as is
.Fluid.Sensors // keep as is

.Air.Fans        // copy all top-level fans
.Air.Sensors     // copy all sensors
.Air.Humidifiers // moved from .Fluid
.Air.Actuators   // Move the Dampers and copy the motor
.Air.HeatExchangers.ConstantEffectiveness  // Copied, for air to air
.Air.HeatExchangers.ConstantEffectivenessWater  // Instantiates Air.HeatExchangers.ConstantEffectiveness
                                                // with port names wat_a, air_a etc.

.Water.Sensors  // copy all sensors except those that only make sense for air
.Water.Boilers  // copied from .Fluid
.Water.Actuators // Move the valves and copy the motor
.Water.HeatExchangers.ConstantEffectiveness     // Copied, for water to water
.Water.HeatExchangers.ConstantEffectivenessAir  // Copied from ConstantEffectivenessWater

The style guide will be that domain specific models (such as a valve) is only in IBPSA.Water.

An alternative design would be to have the distinction between air and water not on a top-level, but deeper inside the tree only as needed:

HVAC
  .HeatGeneration
    .Boilers
    .HeatPumps
      .AirWater
      .WaterWater
  .Distribution
    .UsersGuide
    .Air
      .Ducts
      .Fans  // extends IBPSA.Distribution.BaseClasses.Movers.FlowControlled_dp
    .Water
      .Pipes
      .Pumps  // extends IBPSA.Distribution.BaseClasses.Movers.FlowControlled_dp
    .BaseClasses
      .Movers
        .UsersGuide
        .FlowControlled_dp

The actual copying and search-replace will be done by a python script that scans the library for vendor annotations. For example, the file FlowControlled_dp.mo could contain

__IBPSA(target(name = IBPSA.Air.Fans.FlowControlled_dp,
               extends(redeclare package Medium = Buildings.Media.Air,
                       dp_nominal = 500),
               defaultComponentName = "fan",
               replace = ["fan or pump", "fan";
                        "Fan or pump", "Fan"]),
       target(name = IBPSA.Water.Pumps.FlowControlled_pd,
              extends(redeclare replaceable package Medium = Buildings.Media.Water,
                      dp_nominal = 1000),
              replace = ["fan or pump", "fan";
                        "Fan or pump",  "Fan"]));

where the extends statement will be copied into the declaration of extends IBPSA.Fluid.FlowControlled_dp(...), and the replace will be a global search and replace on the info section. If the text is not found at least once, then an exception will be raised (this allows replacing also larger junks in an info section if needed). Hence, from the above, code such as this will be generated:

within IBPSA.Air.Fan;
// This model was generated from IBPSA.Fluid.Movers.FlowControlled_dp. Do not edit.
model FlowControlled_dp "Fan with controlled head"
 extends IBPSA.Movers.FlowControlled_dp(
   redeclare replaceable package Medium = IBPSA.Media.Air,
   dp_nominal = 1000);
annotation(defaultComponentName = "fan",
Documentation(
info="<html>
... // copied info section, with search and replace applied
</html>",
revisions = "<html>
... // copied html section, no replacement here
</html>"
);
end FlowControlled_dp;

Questions

• Where should all the Movers.Examples be? Should we move, or copy, them to Air and Water based on the medium?
• Is the automated process for copying models meant for a one-time use during the re-structuring, or would this be run more than once? I (Marcus) would imagine that the automation helps for a one-time migration. Afterwards, I'd imagine that we could keep all shared parts of the models in a common BaseClass, extend this base class and possibly add domain-specific model parts to the air and water based models. In this case, I don't see the need to have the // This model was generated from IBPSA.Fluid.Movers.FlowControlled_dp. Do not edit. comment. We may want to add functionality to the fan that the pump does not need. For documentation, I'd add specific documentation to fan and pump and link to either the documentation of the base class or to a Users' Guide that explains the base class and the extended classes.

Notes

1. Shared code such as the Movers.FlowControlled_dp is in IBPSA.Fluid from which it is extended
2. Note that the Medium is replaceable so that it shows up in the parameter window and users can redeclare it or add trace substances C.