classConventions

Information

The Buildings library uses the following conventions, which largely are based on the conventions of the Modelica Standard Library.

Package structure

Packages have usually the following subpackages:

• UsersGuide containing an overall description of the library and how to use it.
• Examples containing models demonstrating the usage of the library.
• Validation containing typically small models that validate a certain behavior of a model.
• Interfaces containing connectors and partial models.
• Types containing type, enumeration and choice definitions.

Naming

1. Class names of models, blocks and packages should start with an upper-case letter and be a noun or a noun with a combination of adjectives and nouns. Use camel-case notation to combine multiple words, such as HeatTransfer. Don't repeat higher level package names, for example, rather than Chillers.CarnotChiller, use Chillers.Carnot.
2. Instance names should be a combination of the first three characters of a word, such as preDro for pressure drop model. Where applicable, a single character can be used if this is generally understood, such as T for temperature, p for pressure, u for control input and y for control output signal. As needed, these can be augmented, for example a controller that outputs a control signal for a valve and a damper may output yVal and yDam.
3. The following variables are frequently used for physical quantities:
   • T for temperature,
   • p for pressure,
   • dp for pressure difference,
   • P for power,
   • E for energy (or Q for thermal energy),
   • X for mass fraction,
   • Q_flow for heat flow rate
   • m_flow for mass flow rate and
   • H_flow for enthalpy flow rate.
4. The nomenclature used in the package Buildings.Utilities.Psychrometrics is as follows,
   • Uppercase X denotes mass fraction per total mass.
   • Lowercase x denotes mass fraction per mass of dry air.
   • The notation z_xy denotes that the function or block has output z and inputs x and y.
   • The symbol pW denotes water vapor pressure, TDewPoi denotes dew point temperature, TWetBul denotes wet bulb temperature, and TDryBul (or simply T) denotes dry bulb temperature.
5. Control input signals usually start with u and control output signals usually start with y, unless use of the physical quantity is clearer.
6. The following strings are frequently used:
   • Prefix use_ for conditionally enabled input signals, such as use_T_in for enabling an input connector for temperature in Buildings.Fluid.Sources.Boundary_pT, or as use_enthalpy in Buildings.Controls.OBC.ASHRAE.G36.AHUs.MultiZone.VAV.Economizers.Subsequences.Enable to flag if it should evaluate outdoor air enthalpy in addition to temperature.
   • Prefix have_ if a controller has a certain input, such as have_CO2Sen in Buildings.Controls.OBC.ASHRAE.G36.TerminalUnits.Reheat.Controller if the zone has a CO₂ sensor.
   • Suffix _flow for a flow variable, such as Q_flow, m_flow and V_flow. See Buildings.Fluid.Sensors.VolumeFlowRate.
   • Suffix _nominal for the design or nominal capacity, i.e., Q_flow_nominal is the capacity of a device that it has at full load, and m_flow_nominal is the design mass flow rate. See Buildings.Fluid.HeatExchangers.HeaterCooler_u.
   • Suffix _small for a small value which is typically used for regularization (to ensure a numerically robust implementation).
   • Suffix Set for set point.
   • Suffix _min (_max) for minimum (maximum), such as TSupCoo_min for the lowest cooling supply air temperature setpoint in Buildings.Controls.OBC.ASHRAE.G36.AHUs.MultiZone.VAV.SetPoints.SupplyTemperature.
7. The two connectors of a domain that have identical declarations and different icons are usually distinguished by _a, _b or _p, _n. Examples are fluid ports port_a and port_b or electrical connectors terminal_p and terminal_n.

Documentation

1. In the html documentation, start additional headings with h4. (The headings h1, h2, h3 must not be used, because they are utilized from the automatically generated documentation.)
2. Comments must be added to each class (package, model, function etc.).
3. The first character should be upper case.
4. For one-line comments of parameters, variables and classes, no period should be used at the end of the comment.

Graphical display

1. The instance name of a component is always displayed in its icon (using the text string "%name") in blue color.
2. A connector class has the instance name definition in the diagram layer and usually not in the icon layer, unless this helps with usability.
3. The value of main parameters, such as nominal capacity, are displayed in the icon in black color in a smaller font size as the instance name if this helps with usability.

Miscellaneous

1. Where applicable, all variable must have units, also if the variable is protected.
2. Each class (i.e., model, block and function) must be used in an example or validation case.