.Dynawo.UsersGuide.NamingConventions

Information

This section contains the naming and style guidelines for the Dynawo 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. It is recommended to draw a small scheme indicating the conventions.

The name of the electrical connector should be terminal for an injector type model, and terminal1 and terminal2 for a branch type model.

Package structure conventions

Each dynamic model should have a .mo file. These models can extend base models. All base models should be gathered in a specific base package.

Each init model should have a .mo file. These models can extend base models that should be gathered in a specific base package.

In package.order, the package containing the base models should be indicated first, followed by each pair of dynamic and initialization models.

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

The names of component instances of a base model should not be used again in the models which extend the base model.

In addition to this, please follow the additional naming conventions below (in that order):

• Min/Max parameters/variables: end with Min/Max
• Start parameters/variables: end with 0
• Per unit parameters/variables: end with Pu (always indicate "in pu" in the comment along with the pu base)

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), I (for absolute value) or id/iq for dq-axis values
• Voltages (phase-to-phase) should be named u (for complex variable), U (for absolute value) or ud/uq for dq-axis values
• Voltages (phase-to-ground) should be named v (for complex variable), V (for absolute value) or vd/vq for dq-axis values
• 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...

Exceptions for initialization models

Initialization models name should end with _INIT. There can be several initialization models for one dynamic model.

The initialization models variables are the parameters of the dynamic models so they should start with an upper case letter.

In an initialization model, the names of component instances should end in "Init", and this ending should never be used for instances of dynamic models.

Types conventions

Preferably use the types defined in the Dynawo.Types package and avoid using plain Real variables.

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 Dynawo imports (alphabetical order)
• extends statements
• Public parameters (including extends)
• Connectors (group them based on functional aspects), inputs/outputs (in that order)
• Blocks (group them based on functional aspects)
• Initial parameters (if not protected)
• Protected parameters followed by protected final parameters
• Protected initial parameters followed by protected initial final parameters
• Protected variables
• Equations: equations first, followed by when equations and if equations, blocks connections at the end
• Annotations: remove minor tool-specific annotations

Public/Protected conventions

Comments and documentation 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. Always give the unit and the pu base. 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 are meant for library developers.

Model implementation

• Use complex numbers (and native associated functions) whenever possible
• Use the flow keyword for init complex current declaration (they could be used in initConnect into Dynawo tool)
• Use discrete Real for non-continuous variables
• Use inner/outer variables for shared general variables
• Use input/output keywords for the inputs/outputs 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)

Graphical view

Try to use one of the Modelica icons or Dynawo icons when creating a model.

Preferred view

Always set a preferred view to your model such as it will be opened by default in this view by Modelica-based environments:

• text view for equation-based models
• diagram view for input/output or block models
• info view for documentation