IDEAS Style Guide

This page provides a checklist that should be used when contributing to a new class (model, block, function, etc.) to the library.

General

1. Follow the conventions as specified in the Modelica IBSPA library and described in the Modelica Buildings library User's Guide.
2. Partial classes and base classes that are not of interest to the user should be stored in a subdirectory called BaseClasses.
3. Do not copy sections of code. Use object inheritance.
4. Implement new components by extending from the partial classes in the respective Interfaces directories, where possible.
5. Use the full package names when instantiating a class, i.e. always starting with IDEAS..

Conventions

1. Class and instance names are written in CamelCase (upper and lower case letters), e.g., ElectricCurrent. If possible, only use the first three letters of a compound name, e.g., EleCur. An underscore is only used at the end of a name to characterise a lower or upper index, e.g., pin_a.
2. Class names always start with an upper-case letter.
3. Instance names, i.e., names of component instances and variables (except for constants), usually start with a lower case letter, with only a few exceptions if this is common sense (such as T for a temperature variable). See the table below for examples and exceptions.
4. Constant names, i.e., names of variables declared with the "constant" prefix, follow the usual naming conventions (= upper and lower case letters) and start usually with an upper case letter, e.g., UniformGravity, SteadyState.
5. The two connectors of a domain that have identical declarations and different icons are usually distinguished by _a, _b or _p, _n. Examples: Flange_a, Flange_b or HeatPort_a, HeatPort_b.

These rules are additions to the basic rules above:

6. Variable names start with the symbol. Example: TSet, T_start, pOut, mFlow_nom (and NOT setTemperature or outletPressure or NomMFlow or something like that)
7. If possible and clear, abbreviate sequences to 3 letters for instances. For long words, this is strongly encouraged; for short (4 and 5-letter words), this is not necessary, although it is possible. Class names do not have to be abbreviated.
8. All variables should be instances of the Modelica.Units.SI package. Examples: Modelica.Units.SI.Temperature or Modelica.Units.SI.MassFlowRate.
9. The Modelica sign convention denotes: flow INTO component is POSITIVE (for mass flow rates, current, etc.) You can remember this by a simple rule: Modelica components are egoistic: getting something is positive for them. This means for electric power: a positive power at a connection => the object consumes electricity.
10. Efficiencies and ratios: no unit, no percentage (1 instead of 100%, also called “base 1”)

Documentation

1. Add a one-line comment to all parameters and variables, including protected ones.
2. Provided a detailed explanation of the implemented physics in the Specifications section in LaTeX.
3. Group similar variables using the group and tab annotation.
4. Add model documentation to the info section.
5. Add author information to the revision section.
6. Run a spell check.
7. For complex packages, provide a User's Guide, and reference the User's Guide in IDEAS.Buildings.UsersGuide.

Equations and Algorithms

1. Avoid events where possible.
2. Only divide by quantities that cannot take on zero.
3. Use SI units in all equations.
4. Use the assert function to check for invalid values of parameters or variables.
5. Use either graphical modelling or textual code. Avoid using both within one class.
6. For computational efficiency, equations shall be differentiable and have a continuous first derivative.
7. Avoid equations where the first derivative with respect to another variable is zero, except at a single point.
8. Do not replace an equation by a constant for a single value, unless the derivative of the original equation is zero for this value.
9. Whenever possible, a Modelica tool should not have to do numerical differentiation. For example, in Dymola, if your model translation log shows Number of numerical Jacobians: 1 (or any number other than zero), then enter on the command line Hidden.PrintFailureToDifferentiate = true; Next, translate the model again to see what functions cannot be differentiated symbolically. Then, implement symbolic derivatives for this function. See implementation of function derivatives.

Type Declarations

1. Declare variables and final parameters that are not of interest to users as protected.

2. Set default parameter values as follows:

   1. If a parameter value can range over a large region, do not provide a default value.

   2. If a parameter value does not vary significantly, provide a default by using its start attribute, e.g. use

      parameter Real eps(start=0.8, min=0, max=1, unit="1") "Heat exchanger effectiveness";

   3. If a parameter value can be precomputed based on other parameters, set its default value to this equation, e.g.

      parameter Medium.MassFlowRate mFloSmall(min=0) = 1E-4*mFloNom;

   4. If a parameter value should not be changed by a user, use the final keyword.

3. For any variable or parameter that may need to be solved numerically, provide a value for the start and ``nominal``attributes.

4. Use types from Modelica.Units.SI where possible.