Model description template

Markdown metadata block


layout: page Shall not be modified

title: Model name try to be as specific as possible

tags: [_tag1, tag2, tag3_] Please pick none, one or several tags for the following categories:

  • Opensource : tag to be added if there is at least one open source implementation of this model
  • CIM model: CIMStatic or CIMDynamic tags can be selected if your model is part of the CIM standard
  • Modeling details: tags giving the modeling details for this model: EMT, Dynamic phasor, shifted frequency, phasor, RMS
  • Model readiness level: indicates the level of maturity of the model:
    • Model exists on paper
    • Model has been implemented in a tool
    • Model has been implemented and validated in tool with a reference or field measures.
    • Model is being used on regular basis in one or several industrial tools
  • Number of phases: Single phase, three phases
  • Standard: select the relevant tag name standard (WECC, CIGRE, IEEE, IEC, etc.) if your model is included in a standard.
  • Code section: if this template contains a Modelica or Openmodelica code section in line with the model description and equations, use the tag CodeImplementation
  • Component type: gives the electrical category of the device: Protection, line, bus, machines, synchronous generator, transformer, controllers, capacitors, sources, excitation system, automatic voltage regulator, PSS, PLL, Governor, load, sensors, wind generation, solar generation, load, HVDC, synchronous condensers, DLR, etc.
  • Implementation tools: software name (EMTP, PSCAD, PSS/E, NEPLAN, dynawo, DPSIM, Power Factory, Matlab, STEPSS, RTDS, Opal RT, powerworld, GE PSLF) to be used as tag if your model is implemented in specific software

date: XX/XX/20XX date of page creation

last-updated: XX/XX/20XX date of last page modification

author name the author of this model

reviewers name the reviewers of this model


Do not provide the title here (to avoid duplicate display) as it should be included in the Metadata block. We recommend including the issue ID generated by Colib GitHub along with the title.

Each model post must be a consistent whole that cannot be subdivided into sub-models without loss of understanding (for example, due to a consistent notation system, intertwined equations, etc.)

Context (mandatory)

A short paragraph reminding the history of the model, in which context it was developed for, what are the physics and the modelling approximations behind it.

References citations can be made pointing to the references section (at the end of the document). Two ways to include a citation:

  • by using footnote links: put [^1] inside the main text and a markdown list at the end of the document.
  • by using a bibtex file: add your bibtexfile in the _bibliography folder. Add a citation inside your text with:

    {% cite DUMMY:2 %}

add bibliography at the end of the document.

Model use, assumptions, validity domain and limitations (mandatory)

Each model is an approximation of the reality, and considers some assumptions.

This section gives details on:

  • the validity domain of the model (frequency range, type of dynamics, type of stability phenomena) that the model covers,
  • the model assumptions (e.g., neglecting the DC side of the converter, simplistic PLL representation)
  • the limitations of the model (what people shouldn’t use the model for)

Model description (mandatory)

This section gives the full description of the different model’s component.

For each component, is given: a brief explanation about the functioning of the component (how it works, what it is made of, which implementation choices are made) and the component equations or control diagram. The author can also point to another component page if the component is already explained in another page. In such case, he clearly needs to make coherence is achieved with the rest of the model in terms of notation, convention, and connection aspects.

  • For the equation system / algorithm : the author can use Latex language, which is fully compatible with markdown. For example: $$ x_{j}^{i} $$. He can also use numbered equations. The variables and parameters should be clearly specified, as well as their type (complex, real, etc.), unit (MW, MVA, etc), and meaning (phase to neutral voltage for the output terminal A). The notation should follow scientific standards.

  • Images can be added for clarity with: <img src="/pages/templates/gaussian.png" alt="Normalized Gaussian curves" The image must be of good quality and more preferably in .svg format.

  • Electric/Electronic/Control/Phasor diagrams: they can be used instead of equations system to describe the component. We invite the author to use the draw.io plugin for github allowing you to make your own diagram easily. The diagram is fully editable with github commit using a graphical interface, and allowing multiple format outputs (for more details, see: draw.io github). if the diagram includes common control block, you can use the already available drawio library in pages/models/controlBlocks/ . For each block a corresponding page is provided describing the block itself, it diagram representation and the corresponding equations/algorithm.

  • Initial equations/boundary conditions: when initial equations or boundary conditions are necessary to fully described the system, a subsection dedicated to those aspects can be added in this section.

Modelica implementation (optional)

This section is a code section that provides the source code for model described above.

The implementation should correspond strictly the equations/diagram/algorithm described before and should have been validated in a tool. The date of the code should be specified at the beginning of the section, the code should be clean, readable and organized. The code can be presented in a markdown code block like this:

function test() {
  console.log("notice the blank line before this function?");
}

Open source implementations (if any)

This section give a list of the different open source implementations of this model.It provides the reader with links and languages/software used for each implementations.

The markdown table can be used to display such list, for example:

This model has been successfully implemented in :

Software URL Language Open-Source License Last consulted date Comments
Software name Link modelica MPL v2.0 XX/0X/20XX Comments can contain implementations details such as validation means, implementations key choices, etc.

Table of references & license

This section lists all the references. It must comply with current citation standards.

A bibtex file can directly be used.

For example: You can insert references manually by using this markdown list links:

<a id="1">[1]</a> Author's name, "Title" Date Journal, doi: 10.1109/>XXXXx46648.2021.9495096 at the end of the document.
<a id="2">[2]</a> Author's name 2, "Title2" Date Journal, doi: 10.1109/>XXXXXXXXX.2021.9495096 at the end of the document.

or by inserting directly the bibtex file biblioagraphy with the following command:

{% bibliography --file references  %}

which gives:

  1. Doe, J. (2100). The Book without Title. Dummy Publisher.
  2. Taylor, A. (2010). The book with a nice title . https://doi.org/10.1016/j.epsr.2020.112811
  3. of Electrical, T. I., & Engineers, E. (2016). IEEE recommended practice for excitation system models for power system stability studies . IEEE Std 421.5-2016. https://home.engineering.iastate.edu/ jdm/ee554/IEEEstd421.5-2016RecPracExSysModsPwrSysStabStudies.pdf
  4. Commission, I. E. (2024). Energy management system application program interface (EMS-API) Part 302: Common information model (CIM) dynamics. IEC 61970-302. https://webstore.iec.ch/preview/info_iec61970-302%7Bed2.0%7Db.pdf
  5. Ferguson, H. H., R. W., & Miller, R. W. (1960). Analytical studies of the brushless excitation system. AIEE Transactions on Power Apparatus and Systems (Part IIIB), Vol. 79.
  6. Gayek, H. W. (1964). Transfer characteristics of brushless aircraft generator systems. IEEE Transactions on Aerospace, Vol. 2, No. 2.
  7. NERC. (2017). Modeling Notification Gas Turbine Governor Modeling. https://www.nerc.com/comm/PC/NERCModelingNotifications/Gas_Turbine_Governor_Modeling.pdf
  8. M. Nagpal, G. K. M., A. Moshref, & Kundur, P. (2001). Experience withtesting and modeling of gas turbines. IEEEPower Engineering Society General Meeting. https://www.nerc.com/comm/PC/NERCModelingNotifications/Gas_Turbine_Governor_Modeling.pdf
  9. system dynamic performance committee Task Force on Turbine-Governor Modeling, P. (2013). Dynamic Models for Turbine-Governors in Power System Studies. IEEE Power & Energy Society PES-TR1 Technical Report. https://site.ieee.org/fw-pes/files/2013/01/PES_TR1.pdf
  10. on Prime Mover, I. E. E. E. W. G. (1973). Dynamic Models for Steam and Hydro Turbines in Power System Studies. IEEE Trans. on PAS, Vol PAS-92. https://ieeexplore.ieee.org/document/141700/authors#authors

--cited command list only the ones that are cited in the page. More details about the citations details can be found at: jekyllScholarCitations

Evaluate