.PowerGrids.UsersGuide.NamingConventions

Information

This section contains the naming and style guidelines for the PowerGrids library development. If you want to contribute to the library, please make sure you follow them strictly, to ensure a consistent style throughout the whole library.

When writing a Modelica model, please respect the general Modelica conventions and follow the recommendations below.

Please always use the English language for the code and comments.

Electrical conventions

For currents and powers, the receptor convention is normally followed, i.e. the value is positive when entering the device. Variables following the opposite generator conventions are available on the component ports; they are marked explicitly with Gen in their name.

Naming conventions

Generalities

Use package namespaces as much as possible to avoid naming conflicts. Do not duplicate parent namespaces in the children model names.

Please follow the Modelica naming conventions.

• Package/Class/Model : start with upper case letter and use camel-case convention, e.g "ElectricCurrent"
• Parameters/Constants: start with an upper case letter
• Variables/Connectors/Component instance : start with lower case letter and use camel-case convention
• Functions: start with lower case letter

In addition to this, please follow the additional naming conventions bellow:

• Start parameters/variables: end with Start
• Per-unit parameters/variables: end with Pu
• Min/Max parameters/variables: end with Min/Max

Exceptions for physical variables

There are some exceptions for the physical variables. Please refer to the list below:

• Frequencies should be named f. A parameter related to a frequency should start with a lower case letter, e.g fACNetwork.
• Currents should be named i (for complex variable) or I (for absolute value)
• Voltages (phase-to-phase) should be named u (for complex variable) or U (for absolute value)
• Voltages (phase-to-ground) should be named v (for complex variable) or V (for absolute value)
• Apparent power should be named s (for complex variable) or S (for absolute value)
• Active power should be named P, reactive power should be named Q
• Impedance should be named Z, resistance should be named R, reactance should be named X,
Admittance should be named Y, conductance should be named G, susceptance should be named B
• Angles should be named according to their name in textbooks (ex: theta)
• Time should be named t (T is used for the temperature). A parameter related to a time should start with a lower case letter, e.g tInteger, t0...

Types conventions

Preferably use the types defined in the PowerGrids.Types package, or possibly locally redefined types with ad-hoc nominal attributes. For other units, please use Modelica.SIunits types. Use the appropriate unit for PerUnit variables. Avoid using plain Real variables that lack dimensional information and prevent automatic dimension checking on physical equations.

Model structure conventions

Generalities

Respect the following order while writing or updating a model:

• Modelica library imports (alphabetical order)
• other libraries imports (alphabetical order)
• internal PowerGrids imports (alphabetical order)
• extends statements
• public items: parameters, connectors (group them based on functional aspects)
• protected items: parameters, variables, blocks (group them based on functional aspects)
• initial equations
• equations

Comments conventions

Comments should start with a capital letter.

• Always comment all models, function, parameters and variables, using the Modelica "comments", explaining concisely but clearly what is their meaning/use. These comments are meant for the library users and automatically show up at various places in the graphical user interface (e.g. in the variables browser to inspect simulation results).
• Use // comments for equations and implementation description (base transformation, model conventions). These comments meant for library developers.

Model implementation

• Use complex numbers (and native associated functions) whenever possible
• Only use per-unit for models which are natively described in per-unit variables, otherwise use SI physical quantities.
• Never introduce explicit scaling factors in physical models, rely on the nominal attribute of variables and on the automatic scaling performed by the Modelica tool instead
• Use discrete Real for non-continuous variables
• Use inner/outer variables for shared general variables
• Use input/output keywords or conectors for the inputs/ouputs seen from the model (at least for control models)
• Component state
  • running describes a state when something is flowing through the device
  • on describes a state when the device is turned on (but no flow may be flowing through)
  • off describes a state when the device is shut down (no flow is expected)